---
title: "Read retained birth-source evidence"
method: GET
path: "/v1/farm/{farm_id}/birth-sources/{source_sms_id}"
tags: ["birth-sources"]
---

# Read retained birth-source evidence

`GET /v1/farm/{farm_id}/birth-sources/{source_sms_id}`

## Request

- Base URL: `https://api.ranch.bot`
- URL: `https://api.ranch.bot/v1/farm/{farm_id}/birth-sources/{source_sms_id}`
- Auth: HTTP bearer

Returns ordered attachment processing status and current farm-matched numeric tag candidates for the original source author with current farm membership. Requires read:records and read:animals for external credentials. No source URLs, signed URLs, raw OCR text, or image bytes are returned. Partial or uncertain candidates require producer selection; this operation writes no farm records.

## Path parameters

- `farm_id` string, uuid, required
- `source_sms_id` string, uuid, required

## Response `200`

Private source evidence

- object
  - `source_sms_id` string, uuid, required
  - `source_message_id` string, nullable, required
  - `stage` 'LEGACY' | 'CONTROL' | 'PENDING' | 'PROCESSING' | 'BLOCKED' | 'FAILED' | 'COMPLETE', required
  - `failure_code` string, nullable, required
  - `media` object[], required
    - `id` string, uuid, required
    - `ordinal` integer, required
    - `file_id` string, nullable, required
    - `content_type` string, nullable, required
    - `state` 'PENDING' | 'RETAINED' | 'FAILED', required
    - `ocr_state` 'PENDING' | 'COMPLETE' | 'FAILED' | 'UNSUPPORTED', required
    - `ocr_version` string, nullable, required
    - `ocr_attempts` integer, required
    - `ocr_failure_code` 'UNSUPPORTED_IMAGE' | 'IMAGE_LIMIT' | 'OCR_UNAVAILABLE' | 'OCR_TIMEOUT' | 'OCR_OUTPUT_LIMIT' | 'OCR_FAILED' | 'null', nullable, required
    - `ocr_completed_at` string, date-time, nullable, required
    - `candidates` object[], required
      - `animal_id` string, uuid, required
      - `identifier_id` string, uuid, required
      - `identifier_value` string, required
      - `normalized_identifier` string, required
      - `is_iso_eid` boolean, required
      - `match_kind` 'exact' | 'suffix' | 'partial', required
      - `confidence` 'high' | 'low', required
      - `requires_selection` boolean, required
      - `supporting_observations` object[], required
        - `media_id` string, uuid, required
        - `digits` string, required
        - `ocr_confidence` number, required
        - `box` object, required
          - `left` number, required
          - `top` number, required
          - `width` number, required
          - `height` number, required
        - `match_kind` 'exact' | 'suffix' | 'partial', required
    - `candidates_truncated` boolean, required: When true, the candidate list requires manual selection.
  - `candidates` object[], required
    - `animal_id` string, uuid, required
    - `identifier_id` string, uuid, required
    - `identifier_value` string, required
    - `normalized_identifier` string, required
    - `is_iso_eid` boolean, required
    - `match_kind` 'exact' | 'suffix' | 'partial', required
    - `confidence` 'high' | 'low', required
    - `requires_selection` boolean, required
    - `supporting_observations` object[], required
      - `media_id` string, uuid, required
      - `digits` string, required
      - `ocr_confidence` number, required
      - `box` object, required
        - `left` number, required
        - `top` number, required
        - `width` number, required
        - `height` number, required
      - `match_kind` 'exact' | 'suffix' | 'partial', required
  - `candidates_truncated` boolean, required: When true, the candidate list requires manual selection.

## Other responses

- `401`: Authentication required
- `403`: Required read scope missing
- `404`: Source unavailable to the current user and farm

---

[API](https://skmtc.dev/ranch/apis/ranch-bot-http-api.md) · [All operations](https://skmtc.dev/ranch/apis/ranch-bot-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ranch/apis/ranch-bot-http-api/revisions/24109d33fa02?raw)