RI Platform
Developer documentation

API Documentation

Reference material and integration guides for the Relational Manager API.

Troubleshooting

Common Errors

  • 401 missing_api_key: No API key supplied.
  • 401 invalid_api_key: API key not recognized or inactive.
  • 403 no_active_license: Organization license not active.
  • 403 no_lenses_available: No lenses configured for the org or platform.
  • 403 unlicensed_lens: One or more requested lens IDs not licensed for this org.
  • 403 insufficient_scope: Updating traffic-light ranges requires org:write.
  • 400 invalid_channel_type: channel_type is not in the allowed list.
  • 400 invalid_request: Schema validation failed.
  • 400 invalid_traffic_light_ranges: Bands are missing, overlapping, gapped, or contain invalid boundaries.
  • 501 persist_not_supported: persist=true is disabled.

Channel Types

  • instant_message, live_chat, chatbot, text_message, whatsapp, messenger, chat
  • email, social_media, web, forum, blog
  • live_conference, live_call
  • podcast, video_recording, audio_recording

Warnings

  • lang '<value>' is not supported; some scoring may be degraded.

Zero Score vs Unscored

  • Read scoring_status on every question.
  • unconfigured and unavailable questions retain score: 0.0 for compatibility but are excluded from the lens aggregate.
  • A lens with no scored questions returns traffic_light: null.
  • scoring_coverage shows the proportion of questions that contributed.
  • Unscored questions return traffic_light: null.

UI Dials

  • Drive dials from each question's indicator_name, score, and traffic_light, not prediction cluster scores.
  • Indicator names are public and lens-specific; underlying metrics remain private.
  • Changing a lens's ranges immediately changes the mapped signal for every question in that lens.

Empty Prescriptions

  • unconfigured and unavailable questions intentionally have no prescriptions.
  • A scored question selects authored low, medium, or high guidance when no contributor prescription exists. Legacy positive questions without authored tiered guidance may still return no question-level prescription.
  • Green lenses return no lens-level prescriptions.
  • Target-driven AI prescriptions are generated separately and are not part of the live scoring call.

Checklist Before Contacting Support

  1. Capture X-Request-Id from the response headers.
  2. Confirm message.conversation_id matches previous_message.conversation_id.
  3. Validate channel_type against the supported list.