---
title: "Invite Referral Partner"
method: POST
path: "/referrals/partners"
tags: ["Referrals"]
---

# Invite Referral Partner

`POST /referrals/partners`

## Request

- Base URL: `https://api.openintake.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openintake.ai/referrals/partners`
- Auth: none declared

Invite an outside referrer (individual, organization, or attorney):
create their portal login and
partner record together, then email a link to set their password.

The login is created without a password and the invite carries a single-use
PasswordResetToken, because /auth/forgot-password cannot bootstrap an
account that has never had one.

## Request body

- CreateReferralPartnerRequest: Add a referrer (individual, organization, or attorney) to the portal. Three ways to give them a login: - a new account, emailed an invite to set their password (the default); - a new account with ``password`` set here, no email (the firm hands it over); - ``existing_user_id``: one of the firm's own OpenIntake users, who signs in to the portal with the login they already have.
  - `name` string, nullable: Required unless existing_user_id is given
  - `firm_name` string, nullable: Optional internal grouping label (e.g. the firm or company several referrers share). Never shown to the referrer.
  - `email` string, email, nullable: Their login; required unless existing_user_id is given
  - `phone_number` string, nullable
  - `existing_user_id` string, uuid, nullable: One of the firm's own users to make a partner (no new account, no email)
  - `password` string, nullable: Set the new account's password now instead of emailing an invite
  - `skip_invite_email` boolean: Developers only: create the partner without sending the invite email and return the set-password link in the response (local dev / demos).

## Response `200`

Successful Response

- ReferralPartnerResponse
  - `referral_partner_id` string, uuid, required
  - `name` string, required
  - `firm_name` string, nullable
  - `email` string, nullable
  - `phone_number` string, nullable
  - `has_login` boolean, required: Whether a portal login exists for this partner
  - `login_kind` 'partner' | 'firm_user', nullable: partner = a portal-only account; firm_user = one of the firm's own users
  - `sa_contact_id` integer, nullable
  - `sa_attorney_contact_id` integer, nullable
  - `referral_source_kind` 'attorney' | 'other' | 'paid', nullable
  - `case_contact_role` string, nullable
  - `intake_performed_by` string, nullable
  - `test_account` boolean: Its referrals never reach SmartAdvocate (always a dry run)
  - `is_active` boolean, required
  - `referral_count` integer
  - `created_at` string, date-time, required
  - `set_password_link` string, nullable: Only returned when a developer invited with skip_invite_email; must be delivered to the partner out of band.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-21** `62b223e8ec22`: 1 info
  - added the optional property `test_account` to the response with the `200` status
- **2026-10-16** `4ceb1e8613ee`: 8 info
  - added the new optional request property `existing_user_id`
  - added the new optional request property `password`
  - the request property `email` became optional
  - the request property `name` became optional
  - …4 more
- **2026-10-16** `b3a39dc007df`: 1 warning, 4 info
  - removed the optional property `sa_firm_contact_id` from the response with the `200` status
  - added the optional property `case_contact_role` to the response with the `200` status
  - added the optional property `intake_performed_by` to the response with the `200` status
  - added the optional property `referral_source_kind` to the response with the `200` status
  - …1 more
- **2026-10-16** `47c26f79c0d8`: 2 info
  - added the optional property `sa_attorney_contact_id` to the response with the `200` status
  - added the optional property `sa_firm_contact_id` to the response with the `200` status
- **2026-09-17** `0afcd7c31ce2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openintake/apis/openintake-api/changes/referrals/partners/post.md)

---

[API](https://skmtc.dev/openintake/apis/openintake-api.md) - [All operations](https://skmtc.dev/openintake/apis/openintake-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openintake/apis/openintake-api/revisions/de90a8dcbc07?raw)