> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Create person reference > Add a reference for the person in the path: the person who gave it (`related_person_id`), how they know each other (`reference_type`), an optional strength and a formatted note. Set `occurred_at` to record when the reference actually happened; it defaults to `created_at`, the same as for person activities. A reference reads from the person in the path to the related person: a `previous_manager` reference added on John with Jane as the related person shows in the app as "John · Previous Manager · Jane". The reference appears on both people, including in their activity timelines (`GET /v1/persons/{id}/activities`, activity type `person_reference`). ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/persons/{id}/references openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. - name: Campaigns description: >- Create and edit email campaigns, enroll people through enrollment batches, and manage who is enrolled. paths: /v1/persons/{id}/references: post: tags: - Persons summary: Create person reference description: >- Add a reference for the person in the path: the person who gave it (`related_person_id`), how they know each other (`reference_type`), an optional strength and a formatted note. Set `occurred_at` to record when the reference actually happened; it defaults to `created_at`, the same as for person activities. A reference reads from the person in the path to the related person: a `previous_manager` reference added on John with Jane as the related person shows in the app as "John · Previous Manager · Jane". The reference appears on both people, including in their activity timelines (`GET /v1/persons/{id}/activities`, activity type `person_reference`). operationId: createPersonReference parameters: - in: path name: id required: true schema: type: string description: Person UUID requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonReferenceCreateRequest' responses: '201': description: Reference created content: application/json: schema: $ref: '#/components/schemas/PersonReferenceResponse' example: success: true data: id: 3f2c8a1e-5b7d-4c9e-8a1f-2d3e4f5a6b7c person_id: 123e4567-e89b-12d3-a456-426614174000 related_person: id: 567e8901-e23c-45d6-e789-012345678901 name: Jane Smith current_job_title: VP Engineering current_company_name: Tech Corp reference_type: previous_manager reference_type_name: Previous Manager reference_strength: high direction: outgoing note: |- Reference call on May 12. Would hire him again for any platform role. note_html: |-

Reference call on May 12.

Would hire him again for any platform role.

created_by: 890e1234-e56f-78a9-b012-345678901234 occurred_at: '2026-05-11T15:00:00Z' created_at: '2026-05-12T16:20:00Z' updated_at: '2026-05-12T16:20:00Z' '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: PersonReferenceCreateRequest: type: object properties: related_person_id: type: string format: uuid description: >- UUID of the other person in the reference. Must be a different person in your workspace. reference_type: type: string minLength: 1 description: >- Reference type key, such as "colleague" or "manager". List the keys for your workspace with GET /v1/persons/reference-types. reference_strength: type: - string - 'null' enum: - low - medium - high description: 'How strong the relationship is: "low", "medium" or "high".' note: type: - string - 'null' description: >- Note about the reference, such as what a reference said. Accepts plain text or HTML (bold, italics, lists, links and headings keep their formatting). Pass null to remove the note. occurred_at: type: string format: date-time description: >- ISO 8601 timestamp for when the reference actually happened (e.g. "2024-01-10T14:00:00Z"). This is distinct from `created_at`, which is a system-managed timestamp for when the reference was written and cannot be set by the caller. Use `occurred_at` to backdate a reference taken earlier. If omitted, it defaults to `created_at`. required: - related_person_id - reference_type PersonReferenceResponse: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/PersonReference' required: - success - data PersonReference: type: object properties: id: type: string format: uuid description: Reference UUID. person_id: type: string format: uuid description: UUID of the person in the request path. related_person: type: object properties: id: type: string format: uuid description: Other person UUID. name: type: - string - 'null' description: Other person full name. current_job_title: type: - string - 'null' description: Other person current job title. current_company_name: type: - string - 'null' description: Other person current employer name. required: - id - name - current_job_title - current_company_name description: The other person in the reference. reference_type: type: string description: Reference type key. reference_type_name: type: string description: Display name of the reference type, as shown in the app. reference_strength: type: - string - 'null' enum: - low - medium - high description: How strong the relationship is. Null when not set. direction: type: string enum: - outgoing - incoming description: >- "outgoing" when the reference was added on the person in the path, "incoming" when it was added on the other person. note: type: - string - 'null' description: Plain-text note. Null when the reference has no note. note_html: type: - string - 'null' description: >- The note as HTML, keeping its formatting. Null when the reference has no note. created_by: type: - string - 'null' format: uuid description: >- UUID of the team member who added the reference. Matches IDs from GET /v1/team-members. occurred_at: type: string description: >- ISO 8601 timestamp for when the reference happened. Defaults to `created_at`; set it on create or update to backdate. created_at: type: string description: ISO 8601 timestamp for when the reference was written. updated_at: type: string description: ISO 8601 timestamp. required: - id - person_id - related_person - reference_type - reference_type_name - reference_strength - direction - note - note_html - created_by - occurred_at - created_at - updated_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.