> ## Documentation Index > Fetch the complete documentation index at: https://docs.sideshift.app/llms.txt > Use this file to discover all available pages before exploring further. # Search recruit students > search recruit students. Requires the `recruit:read` scope. ## OpenAPI ````yaml /openapi/oauth.yaml post /recruit/students openapi: 3.1.0 info: title: SideShift OAuth API version: 1.0.0 description: | The SideShift OAuth API is a scoped, OAuth 2.1 + OIDC-style authenticated integration surface (served at `/api/oauth/v1`) that lets external apps and AI agents operate a SideShift company on a user's behalf — reading and managing campaigns, contracts, creators, applications, posts, payouts, invoices, messages, and company settings — under explicit, per-scope consent. Every request is bound to the tenant (company) and the exact scopes the user granted, so an integration can only do what it was authorized to do. The same capabilities are also exposed through a remote MCP server at `POST /api/mcp` for AI agents that speak the Model Context Protocol. ### Authentication Access is granted through a standard OAuth flow: 1. **Register a client** with Dynamic Client Registration to obtain a `client_id` (and, for confidential clients, a secret). 2. **Request authorization** via the authorization-code grant with PKCE (`S256`). The user is shown a consent screen and picks the company (tenant) and scopes to grant. 3. **Exchange the code** at the token endpoint for a short-lived bearer access token (and a refresh token). 4. **Refresh** with the refresh-token grant; refresh tokens rotate on every use. See the **OAuth Registration**, **OAuth Authorization**, **OAuth Token**, and **OAuth Discovery** sections for the endpoint details. The protocol follows RFC 6749, 7009, 7591, 7592, 7636, 8414, 9068, and 9728. ### MCP server SideShift also exposes a remote Model Context Protocol (MCP) server at `POST /api/mcp`, using the Streamable-HTTP transport. It fronts the **same** OAuth-scoped capabilities as the REST resources, so an AI agent can operate a SideShift company through MCP tools instead of raw HTTP calls. **Connecting a client.** Point any MCP client at `https://app.sideshift.app/api/mcp`. It authenticates with the **same** OAuth 2.1 flow described above — register a client, run authorization-code + PKCE, and obtain a bearer access token; there is no MCP-specific auth scheme. Tokens minted for MCP are multi-audience, so a single token works for both `/api/oauth/v1` and `/api/mcp`. If a request arrives unauthorized, the server replies `401` with a `WWW-Authenticate` challenge that points at the RFC 9728 protected-resource metadata, letting compliant clients auto-discover the authorization server. **What you get.** Every capability scope maps to tools, and the tool set mirrors the REST surface plus a `whoami` tool. Read scopes expose read-only tools; write and sensitive tools carry a confirmation guardrail in their description. Sensitive tools — those that move money or trigger outbound side-effects — are rejected for sandbox/test grants and can be globally disabled with the `MCP_SAFE_MODE` server flag. The claim-link capability is available as the `create_quickpay_claim_link` tool. ### Conventions - **Pagination** — list endpoints return `{ data, nextCursor, hasMore }`. Pass the opaque `cursor` from `nextCursor` to fetch the next page, plus an optional `limit` (default 25, max 100). - **Errors** — every error response uses the envelope `{ error: { code, message, requestId } }`. Include `requestId` when contacting support. - **Idempotency** — an `Idempotency-Key` header is honored on every POST, PATCH, and PUT, and is **required** on money-moving writes so a retried request never double-charges. - **Rate limiting** — every response carries `X-RateLimit-*` headers, and a `WWW-Authenticate` header accompanies 401 and 403 responses. ### Sandbox & sensitive operations Test/sandbox grants can exercise reads and safe writes, but requests that move money or trigger outbound side-effects (payouts, sending invoices or messages, external re-scrapes) are rejected. Money-moving endpoints and campaign analytics-history validation/import requests require an `Idempotency-Key`. contact: name: SideShift API url: https://app.sideshift.app servers: - url: https://app.sideshift.app/api/oauth/v1 description: Production security: - oauth2: [] tags: - name: Campaigns description: Programs/campaigns and their payment structures. - name: Contracts description: Creator contracts. - name: Creators description: Creator roster, collections, and campaign invites. - name: Applications description: Campaign applications (creator handle requests) and their review. - name: Posts description: Tracked creator posts, their metrics history, and CSV export. - name: Payouts description: >- Payout history and pending-payout calculations, plus executing contract payouts, one-time and custom bonuses, and Quick Pay. - name: Invoices description: Invoices — list, get, create, send, and void. - name: Messages description: > Direct-message conversations: list the company's conversations, read a conversation's messages, and send a message (as the company). Messages are delivered via the company's connected chat when available and always persisted; a single conversation is bound to the token's company tenant. - name: Settings description: > Company settings and profile. `GET/PATCH /settings` exposes a server-side **allowlist** of mutable fields (profile/contact/socials/signing); reads and writes never include plan, billing, subscription, permissions, credits, or verification fields. `GET /company` returns the read-only company profile. - name: Invites description: > Campaign/program invite links — list, create, and revoke shareable invites that let creators join a campaign. Team-member invites are managed under the Team tag. - name: OAuth Registration description: > Dynamic Client Registration (RFC 7591) and client configuration management (RFC 7592). Open registration is per-IP rate-limited; management requires the one-time `registration_access_token` returned at registration. - name: OAuth Authorization description: > The authorization endpoint (RFC 6749 §4.1, PKCE S256 required) and the in-session consent bridge that records the user's tenant + scope grant and mints the authorization code. - name: OAuth Token description: > Token issuance (RFC 6749: authorization_code, refresh_token, client_credentials) and revocation (RFC 7009). Form-encoded; responses are `no-store`. - name: OAuth Discovery description: > Public discovery documents — authorization-server metadata (RFC 8414), protected-resource metadata (RFC 9728), and the signing-key JWKS. - name: Agencies description: > Agency-level management for parent companies and their client subaccounts — dashboards, cross-account creator and program rollups, per-client billing, and payout cashflow forecasting. - name: Applicants description: > Review and manage the people who apply to a company's jobs: filter and list applicants, view counts and top posts, bookmark, update status, export to CSV, and open applicant support channels. - name: Billing description: > Subscription and payment-method management — view billing history and subscription status, set the default payment method, preview plan changes, cancel a subscription, and mint browser billing handoff links. - name: Booking description: >- Booking-calendar configuration for scheduling calls with creators and agencies. - name: Brand Content Pages description: > Create, update, and list a company's brand content pages — the public pages that present the brand to creators. - name: Brand Livestream description: Brand live-stream events and their configuration. - name: Brand Verification description: Check a company's brand-verification status. - name: Community Courses description: Educational courses published to a brand's creator community. - name: Community Offers description: Promotional offers and deals published to a brand's creator community. - name: Companies description: > Manage the companies (and agency subaccounts) a user belongs to — create and list companies, read and update company and invoicing profiles, and propagate name, logo, and niche changes across programs and jobs. - name: Conversations description: > Manage direct-message conversations — create threads, add or remove group members, rename, forward messages, and add reactions. - name: Creator Collections description: Organize creators into named collections and manage their membership. - name: Discover description: > The Discover marketplace surface — publish and manage a company's Discover listing, handle qualified lead-form submissions, configure booking hosts, and message agencies. - name: Disputes description: >- View and resolve creator-payment disputes, including uploading counter-evidence. - name: Integrations description: > Connect and configure third-party integrations such as Slack — manage channels, workflow templates, OAuth connections, and test deliveries. - name: Jobs description: >- Post and manage marketplace job listings — create, update, boost, repost, and change job status. - name: Performance description: >- Brand-facing performance observability + creator matching (manually provisioned — SideShift must enable the Performance API for the company). - name: Quick-Pay description: > Send fast, wallet-funded payments to creators — claim links, approval workflows, recurring schedules, reusable templates, and drafts. - name: Recruit description: > Search for and recruit creators — browse candidate profiles, bookmark prospects, and send recruitment invites. - name: Team description: > Manage a company's team — list members and seat usage, invite new members, update permissions and roles, and remove members. - name: Wallet description: > View and move funds in a company's wallet — balances, ledger history, and transfers between an agency and its subaccounts. - name: Video Submissions description: > Review creator video submissions for a company's campaigns, and remove submissions along with the posts they created. - name: Analytics description: Analytics operations. - name: Verifications description: Read identity verification status, profile details, and required actions. paths: /recruit/students: post: tags: - Recruit summary: Search recruit students description: search recruit students. Requires the `recruit:read` scope. operationId: postRecruitStudents requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RecruitStudentsRequest' responses: '200': description: Paginated recruit-candidate search results. content: application/json: schema: $ref: '#/components/schemas/RecruitStudentsEnvelope' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientScope' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' security: - oauth2: - recruit:read components: schemas: RecruitStudentsRequest: type: object description: >- Search recruit students. The companyId is injected from the OAuth grant and must not be sent by the client. OAuth anti-enumeration ceilings apply: batchSize is clamped to 25 and page (and the cursor's nextTypesensePage) may not exceed 10. additionalProperties: true properties: batchSize: type: integer minimum: 1 maximum: 25 default: 21 description: >- Results per batch. Schema allows up to 50, but the OAuth path clamps any value above 25 down to 25. page: type: integer minimum: 1 maximum: 10 default: 1 description: Page number. Over OAuth, values above 10 are rejected with 400. lastDoc: $ref: '#/components/schemas/RecruitStudentsLastDoc' jobId: type: - string - 'null' description: Filter by job id. searchTerm: type: string maxLength: 120 default: '' description: Search term for candidate names/profiles. filters: $ref: '#/components/schemas/RecruitStudentFilters' RecruitStudentsEnvelope: type: object required: - data properties: data: $ref: '#/components/schemas/RecruitStudentsResult' RecruitStudentsLastDoc: type: object additionalProperties: false description: >- Pagination cursor echoed from a previous response. Over OAuth, nextTypesensePage is capped at 10. properties: lastDocId: type: - string - 'null' minLength: 1 description: Last document id (bookmark path). queryMode: type: string enum: - paid - regular nextTypesensePage: type: integer minimum: 1 description: Typesense continuation page to resume scanning at. skipWithinPage: type: integer minimum: 0 maximum: 1000 description: Number of hits to skip within the resumed page. RecruitStudentFilters: type: object description: >- Advanced candidate-search filters. All fields optional; mirrors the platform recruit search filter set. additionalProperties: true properties: q: type: string maxLength: 120 default: '' description: Free-text query applied within the filters. creatorVerified: type: boolean default: false description: Only verified creators. hasTopPosts: type: boolean default: false description: Only creators with top-performing posts. hasThreePosts: type: boolean default: false description: Only creators with at least three posts. hasTikTok: type: boolean default: false description: Only creators with a linked TikTok. hasInstagram: type: boolean default: false description: Only creators with a linked Instagram. usBased: type: boolean default: false description: Only US-based creators (mutually exclusive with nonUS). nonUS: type: boolean default: false description: Only non-US creators (mutually exclusive with usBased). isVerified: type: boolean description: Legacy verified toggle (applicants). minTikTokPosts: type: boolean description: Legacy minimum-TikTok-posts toggle (applicants). country: type: string maxLength: 80 description: Legacy single-country filter (applicants). hideRepeatApplicants: type: boolean description: Exclude repeat applicants (applicants). grades: type: array items: type: string minLength: 1 maxLength: 80 maxItems: 20 default: [] description: Grade/academic-level labels to include. schools: type: array items: type: string minLength: 1 maxLength: 160 maxItems: 30 default: [] description: Schools to include. genders: type: array items: type: string enum: - male - female - other - prefer_not_to_say - unknown maxItems: 5 default: [] description: Genders to include. age: type: object additionalProperties: false description: Age range (min/max, 13-120). max must be >= min. properties: min: type: integer minimum: 13 maximum: 120 max: type: integer minimum: 13 maximum: 120 earningsCents: $ref: '#/components/schemas/RecruitNumericRange' description: Lifetime earnings range, in cents. views: $ref: '#/components/schemas/RecruitNumericRange' description: Total views range. posts: $ref: '#/components/schemas/RecruitNumericRange' description: Total posts range. xp: $ref: '#/components/schemas/RecruitNumericRange' description: XP range. rating: type: object additionalProperties: false properties: min: type: number minimum: 0 maximum: 5 description: Minimum average rating (0-5). reviews: type: object additionalProperties: false properties: min: type: integer minimum: 0 maximum: 1000000 description: Minimum review count. certificationTypes: type: array items: type: string enum: - fast_responder - reliable_interviewer - cpm_mercenary - zero_cancel_streak - never_misses_post maxItems: 10 default: [] description: Certification types to require. minCertifications: type: integer minimum: 0 maximum: 50 description: Minimum number of active certifications. achievementKeys: type: array items: type: string maxItems: 15 default: [] description: Achievement keys to require. achievementMinTierByKey: type: object additionalProperties: type: string enum: - base - level1 - level2 - level3 - level4 - level5 - level6 - level7 - level8 - level9 - level10 - level11 description: >- Per-achievement minimum tier, keyed by achievement key. Keys must be a subset of achievementKeys (at most 15). minUnlockedAchievements: type: integer minimum: 0 maximum: 200 description: Minimum number of unlocked achievements. locations: type: array items: type: string minLength: 1 maxLength: 120 maxItems: 20 default: [] description: Locations to include. niches: type: array items: type: string minLength: 1 maxLength: 80 maxItems: 18 default: [] description: Content niches to include. countries: type: array items: type: string minLength: 1 maxLength: 80 maxItems: 20 default: [] description: Countries to include. trainingProgress: type: object additionalProperties: false description: >- Training-progress percent range (min/max, 0-100). max must be >= min. properties: min: type: integer minimum: 0 maximum: 100 max: type: integer minimum: 0 maximum: 100 minRank: type: integer minimum: 1 maximum: 10 description: Minimum leaderboard rank (1-10). showBookmarkedOnly: type: boolean default: false description: Only return candidates already bookmarked for the job. hideMessaged: type: boolean default: false description: Exclude candidates that have already been messaged. messagedUserIds: type: array items: type: string minLength: 1 maxItems: 50000 default: [] description: User ids already messaged (used with hideMessaged). hideAppliedToJobId: type: string minLength: 1 maxLength: 128 description: >- Exclude candidates who already applied to this job id (must be a job owned by your company). RecruitStudentsResult: type: object additionalProperties: true required: - students - lastDoc - pagination - filters properties: students: type: array items: $ref: '#/components/schemas/RecruitStudent' description: Matched candidates (phone stripped). lastDoc: description: >- Pagination cursor to pass back as lastDoc on the next request, or null when exhausted. oneOf: - $ref: '#/components/schemas/RecruitStudentsLastDoc' - type: 'null' pagination: $ref: '#/components/schemas/RecruitStudentsPagination' filters: type: object additionalProperties: true description: Echo of the raw filters that were applied. ErrorEnvelope: type: object required: - error additionalProperties: false properties: error: type: object required: - code - message - requestId properties: code: type: string enum: - invalid_request - unauthorized - insufficient_scope - forbidden - subscription_required - not_found - conflict - rate_limited - idempotency_conflict - upstream_error - internal message: type: string requestId: type: string meta: type: object additionalProperties: true RecruitNumericRange: type: object additionalProperties: false properties: min: type: number description: Lower bound (inclusive), >= 0. max: type: number description: Upper bound (inclusive); must be >= min. RecruitStudent: type: object description: >- An enriched recruit candidate. The phone field is redacted/stripped before leaving the server. Additional fields may be present. additionalProperties: true required: - userId - name - college - major - academicLevel - hometown - profileImageUrl - oneLiner - creatorVerified - superUser - instagram - tiktok - linkedin - topPosts - niches - pastWork - hasInstagram - hasTikTok - hasTopPosts - usBased - hasBeenPaid properties: userId: type: string name: type: string college: type: string major: type: string academicLevel: type: string hometown: type: string profileImageUrl: type: string oneLiner: type: string creatorVerified: type: boolean superUser: type: boolean instagram: type: string tiktok: type: string linkedin: type: string topPosts: type: array items: {} niches: type: array items: type: string experiences: type: array items: {} involvement: type: array items: {} pastWork: type: array items: {} lastActive: description: >- Last-active timestamp (Date, unix, or Firestore-timestamp-derived; shape varies by source). hasInstagram: type: boolean hasTikTok: type: boolean hasTopPosts: type: boolean hasThreePosts: type: boolean usBased: type: - boolean - 'null' description: true/false when known, null when unknown. hasBeenPaid: type: boolean xp: type: number country: type: string stripeCountry: type: string location: type: string state: type: string city: type: string region: type: string gender: type: string birthday: type: string birthdayTimestamp: type: number certifications: type: array items: {} achievementProgress: type: array items: {} creatorLeaderboard: {} totalViews: type: number totalEarnings: type: number averageRating: type: number reviewCount: type: number graduationStatus: type: string graduationYear: type: number trainingProgressPercent: type: number trainingNodesCompleted: type: number activeCertificationTypes: type: array items: type: string activeCertificationCount: type: number unlockedAchievementKeys: type: array items: type: string unlockedAchievementCount: type: number RecruitStudentsPagination: type: object additionalProperties: true required: - currentPage - pageSize - hasMore - lastDocId - totalReturned - totalMatched - messagedIdsCount - exhaustedNonMessaged properties: currentPage: type: integer pageSize: type: integer hasMore: type: boolean lastDocId: type: - string - 'null' totalReturned: type: integer totalMatched: type: - integer - 'null' description: >- Total candidates matched (Typesense nbHits, or filtered-set size on the bookmark path); may be null. messagedIdsCount: type: integer exhaustedNonMessaged: type: boolean scanPages: type: integer description: Number of Typesense pages scanned (Typesense path only). responses: Unauthorized: description: Missing, expired, or revoked access token. headers: WWW-Authenticate: description: RFC 6750/9728 challenge. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unauthorized message: Missing bearer access token requestId: req_... InsufficientScope: description: The token does not carry the required scope. headers: WWW-Authenticate: description: RFC 6750/9728 challenge with the required scope. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: insufficient_scope message: Requires scope 'campaigns:write' requestId: req_... NotFound: description: The resource does not exist (or belongs to another tenant). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: not_found message: Resource not found requestId: req_... RateLimited: description: Too many requests for this client + company. headers: Retry-After: description: Seconds until the window resets. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limited message: Rate limit exceeded requestId: req_... securitySchemes: oauth2: type: oauth2 description: > OAuth 2.1 authorization code + PKCE (S256). Tokens are tenant-bound (`company_id`) and scoped. Discover endpoints via `/.well-known/oauth-authorization-server`. flows: authorizationCode: authorizationUrl: https://app.sideshift.app/api/oauth/v1/authorize tokenUrl: https://app.sideshift.app/api/oauth/v1/token refreshUrl: https://app.sideshift.app/api/oauth/v1/token scopes: campaigns:read: Read campaigns and payment structures campaigns:write: Create/update/archive campaigns and payment structures applications:read: Read campaign applications (handle requests) applications:write: Approve/reject campaign applications contracts:read: Read contracts contracts:write: Create and cancel contracts creators:read: Read creators and collections creators:write: Create collections and campaign invites posts:read: Read tracked posts, their metrics history, and exports payouts:read: Read payout history, pending payouts, and wallet stats payouts:write: Execute contract payouts and Quick Pay (sensitive — moves money) invoices:read: Read invoices invoices:write: Create, send, and void invoices messages:read: Read conversations and messages messages:write: Send messages settings:read: Read company settings and profile settings:write: >- Update company settings (allowlisted) and create/revoke invites (sensitive) offline_access: Optional OIDC signal for offline access agencies:write: >- Update agency program/contract/client notes, program status, and client archive status agencies:read: >- Read agency dashboard, client lists, creator details, and payment receipts agency-billing:write: >- Update agency billing info, generate subscription links, toggle separate subs, and assign free clients — this moves money. agency-billing:read: Read your agency billing configuration. applicants:read: >- Read access to applicants, including filtered lists, counts, and export applicants:write: >- Write access to update applicant status, bookmarks, and resolve support channels billing:write: >- Manage subscription, payment methods, and bank accounts — this changes what you are charged. billing:read: >- Read subscription status, payment methods, bank-account status, and upgrade previews. booking:write: >- Create and modify bookings, send booking requirements, and other write operations brand-content-pages:read: >- List and view brand content pages (public published pages visible to all, drafts visible to writers only) brand-content-pages:write: >- Create, update, and manage brand content pages (create drafts, publish, manage public share tokens) brand-livestream:write: >- Start/end livestreams, mint viewer tokens, rotate stream keys, and manage egress. brand-livestream:read: >- Read active livestreams, recordings, and settings for brand livestreams. brand-livestream:settings: Update chat and moderation settings for brand livestreams. brand-verification:write: Create brand verification requests and prepare document uploads brand-verification:read: Read access to brand verification status and request history brand-performance:read: >- Read own campaign spend/delivery health and creator-match shortlists (manually provisioned — SideShift must enable the Performance API) agency-performance:read: >- Read performance data for every client brand in your agency subtree — health, scorecards, creator relationships, and a portfolio rollup (agency accounts; manually provisioned) community-courses:read: Read-only access to community course content and metadata community-courses:write: >- Create, update, and delete community courses (educational content management) community-offers:checkout: >- Create checkout sessions for community offer purchases (involves payment processing) community-offers:write: >- Create, update, and delete community offers, promo codes, and Discord integration settings community-offers:membership: >- Link and resolve community offer memberships from purchases (involves payment processing) community-offers:read: Read community offers, promo codes, and membership data discover:read: Read your Discover marketplace offer/listing. discover:write: Publish, update, or remove your Discover marketplace offer. disputes:write: >- Resolve disputes and submit counter-evidence — this can move money. disputes:read: Read creator-payment disputes and their evidence. integrations:read: Read Slack integrations, channels, templates, and configuration integrations:write: >- Create, update, and delete Slack integrations, channels, templates, and workflows jobs:write: >- Create new jobs and update existing jobs, including changing posting status, reposts, and job management. Costs job posting credits for new jobs. jobs:read: >- List and read job data, including duplicate target companies. Read-only access to job details. quick-pay:write: >- Create/update/send Quick-Pay drafts, schedules, templates, and approvals — sending moves money to creators. quick-pay:read: >- Read Quick-Pay drafts, schedules, templates, approvals, pending payments, and recent recipients. recruit:read: Search recruit students and view bookmarked recruits recruit:write: Send recruit invites, manage bookmarks, and mint action tokens team:read: >- Read access to team members list and company invites. Allows viewing member details, permissions, and pending invitations. team:write: >- Write access to add, remove, and update team members, and create/send team invitations. wallet:read: Read your company/agency wallet balance, summary, and ledger. wallet:write: >- Top up (Stripe/bank transfer), reconcile, transfer balance, and record ledger entries — this moves money. video-submissions:write: >- Approve, reject, or request revisions on video submissions, and delete submissions. video-submissions:read: >- Read creator video submissions for your campaigns, including review status. posts:write: >- Set post approval status, mark/clear deletion, and manage analytics tags. booking:read: Read creator booking settings, booking intents, and service types. analytics:read: Read analytics and performance data. verification:read: >- Read your identity verification status, profile, and required actions. ````