Information Capture Requests (ICR)

This quick reference guide shows you how to use Oho Information Capture Requests (ICRs) to collect and validate information from constituents.

Overview

Information Capture Requests (ICRs) allow you to request specific information from constituents, such as background checks, credentials, or other documentation. The ICR system handles the workflow of sending requests, collecting responses, and managing attachments.

Base URL: https://app.weareoho.com/api

Authentication: Required (Bearer token)

Content-Type: application/json

Key Features:

✅ Create ICRs with constituent data
✅ Manage screening packages
✅ Upload and manage attachments
✅ Perform actions (resend, update, cancel)
✅ Track available validation types

Prerequisites

Before using the ICR API, ensure you have:

An active Oho account with API access
A valid API authentication token (see Authentication Guide)
Your organization set up and verified
At least one screening package configured (see below)

Setting Up Screening Packages

Before you can create ICRs via the API, you need to set up screening packages in your Oho instance. Screening packages define what information and accreditations will be collected from constituents.

Required First Step

You must create at least one screening package before you can use the ICR API. The screening_package_code is a required field in all ICR creation requests.

What is a Screening Package?

A screening package is a collection of accreditations and accreditation groups bundled together for someone to provide information for. For example, a screening package might include WWCC, Visa & Licence checks.

An accreditation group is a single or set of accreditation types where information for only one type is required. For example, to prove Australian right-to-work status, someone can provide one of the following: a Visa, Birth Certificate, or Australian Passport. These would be grouped in an accreditation group together.

Creating a Screening Package

Navigate to Screening Package Settings
- Log in to your Oho instance
- Go to Settings → Screening Package Settings
Create New Package
- Click the "Create New Package" button
- Enter a descriptive Package Name (e.g., "New Hire Checks", "Contractor Verification")
- Set a unique Package Code (e.g., "new-hire", "contractor-basic")
- Add one or more Accreditation Groups to define what information is required
Configure Accreditation Groups
- Each group represents a set of acceptable credentials
- Example: A "Right to Work" group might include Birth Certificate, Passport, or Visa options
- Constituents will need to provide one accreditation from each group
Save and Note the Package Code
- After saving, your package will appear in the Screening Packages table
- The Package Code column shows the code you'll use in API requests
- This code is what you'll pass as screening_package_code in your API calls

Finding Your Package Code

To find the package code for API use:

Go to Settings → Screening Package Settings
Locate your package in the Screening Packages table
The Package Code column displays the code (e.g., "ben-ndws", "test1-package", "showcase")
Use this exact code value in your screening_package_code field when creating ICRs

Example from Settings:

Package Name	Package Code	# of Accreditation Groups
New Hire Package	new-hire	2 groups
Contractor Basic	contractor-basic	1 group
Full Screening	full-screening	3 groups

When creating an ICR for "New Hire Package", you would use:

{
  "screening_package_code": "new-hire",
  ...
}

Quick Start

1. Create Constituent with ICR

Create a new constituent and initiate an ICR in a single request.

Endpoint: POST /api/oneoffchecks/ensure_constituent_with_icr

Example Request:

curl -X POST https://app.weareoho.com/api/oneoffchecks/ensure_constituent_with_icr \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "constituent": {
      "first_name": "Jane",
      "middle_name": "Doe",
      "surname": "Smith",
      "email": "jane.smith@example.com",
      "mobile_number": "+61412345678",
      "birth_date": "1990-05-15",
      "external_id": "A045312",
      "position_number": "P12345"
    },
    "screening_package_code": "PACKAGE_CODE",
    "send_link_to_applicant": true
  }'

Required Fields:

constituent.first_name - First/given name
constituent.surname - Surname/family name
constituent.email - Email address for notifications
screening_package_code - The screening package to use

Organization Field

When creating constituents, the API typically associates them with your authenticated organization. If you need to specify a different organization or create a new one, include the constituent.organization object with at minimum the name field. For most use cases, this field can be omitted.

Optional Fields:

constituent.external_id - External reference ID from your source system (e.g., HR system employee ID, ATS candidate ID) for tracking and reconciliation
constituent.position_number - Position or role identifier from your source system (e.g., job requisition number, position code)
constituent.mobile_number - Mobile contact number
constituent.birth_date - Date of birth (YYYY-MM-DD)
send_link_to_applicant - Whether to email the applicant (default: true)
background_check_id - Link to existing background check

Response:

{
  "constituent_id": 12345,
  "continue_url": "https://example.url",
  "info_capture_request_id": "123456",
  "token": "ase0q31043"
}

Response Fields:

constituent_id - Unique identifier for the constituent in Oho
info_capture_request_id - Unique ICR identifier for tracking and subsequent API calls
continue_url - Direct link for the constituent to complete the ICR (useful when send_link_to_applicant: false)
token - Authentication token included in the continue_url for security

Using the ICR ID

The info_capture_request_id from the response (e.g., "123456") is used as the {icr_id} path parameter in subsequent API calls. For example, if you receive "info_capture_request_id": "123456", you would call:

POST /api/info_capture_request/123456/action?action=resend_email

Perform ICR Actions

Perform actions on an existing ICR such as resending emails, updating, or canceling.

Endpoint: POST /api/info_capture_request/{icr_id}/action

Available Actions:

resend_email - Resend the ICR email to the constituent
update - Update the ICR details
cancel_request - Cancel the ICR
onboard_constituent - Onboard the constituent

Example - Resend Email:

curl -X POST "https://app.weareoho.com/api/info_capture_request/abc123/action?action=resend_email" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example - Cancel Request:

curl -X POST "https://app.weareoho.com/api/info_capture_request/abc123/action?action=cancel_request" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters:

action - Action to perform (required)
organization_id - Organization ID (optional)
onboarding_organization_id - Onboarding organization ID (optional)

Manage Attachments

Upload, retrieve, or delete attachments associated with an ICR.

Upload Attachment:

POST /api/info_capture_request/{icr_id}/attachments

Get Attachments:

GET /api/info_capture_request/{icr_id}/attachments

Delete Attachment:

DELETE /api/info_capture_request/attachments/{attachment_id}

Get Next Actions

Retrieve available next actions for an ICR.

Endpoint: GET /api/info_capture_request/{icr_id}/next_actions

curl -X GET https://app.weareoho.com/api/info_capture_request/abc123/next_actions \
  -H "Authorization: Bearer YOUR_TOKEN"

Common Workflows

Complete ICR Workflow

The typical ICR lifecycle: Create → Send Link → Constituent Completes → Review & Approve. The API handles the first two steps automatically when send_link_to_applicant: true.

Workflow 1: Create and Send ICR

Set up a screening package in Settings → Screening Package Settings (see Setting Up Screening Packages)
Create constituent with ICR using POST /api/oneoffchecks/ensure_constituent_with_icr with your screening package code
System automatically sends email to constituent (if send_link_to_applicant: true)
Constituent receives link to complete information request
Monitor ICR status via your dashboard

Workflow 2: Resend ICR Email

Get ICR ID from initial creation or your records
Call POST /api/info_capture_request/{icr_id}/action?action=resend_email
Constituent receives new email with link

Workflow 3: Cancel ICR

Identify ICR to cancel
Call POST /api/info_capture_request/{icr_id}/action?action=cancel_request
ICR status updated to cancelled

Error Responses

401 Unauthorized

{
  "status": 401,
  "message": "You are not authorized to view this resource"
}

Solutions:

Verify your API token is valid
Check Authorization: Bearer YOUR_TOKEN header format
Ensure your user account is verified

403 Forbidden

{
  "status": 403,
  "message": "User email is not verified"
}

Solution: Verify your user email address before making API requests.

Best Practices

Security Best Practices

Never log or expose tokens: The token and continue_url in API responses contain sensitive authentication data
Use HTTPS only: Always connect to the API using HTTPS
Protect API keys: Store your Bearer token securely and never embed it in client-side code
Rotate credentials: Regularly rotate your API authentication tokens

1. Always Provide Contact Information

Include both email and mobile_number when creating constituents to ensure they can be reached.

2. Use Meaningful Screening Packages

Select the appropriate screening_package_code based on the checks required for the constituent's role. Create well-organized screening packages with descriptive names and codes in your Oho instance settings. See Setting Up Screening Packages for details.

3. Set Appropriate Send Flags

Use send_link_to_applicant: false when you want to manually send the link, or true to send automatically.

When to Use send_link_to_applicant

true (default): Oho automatically emails the constituent with the ICR link. Best for standard workflows.
false: You receive the continue_url in the response and can send it to the constituent through your own channels (SMS, custom email, portal, etc.). Best for custom communication workflows.

4. Handle Errors Gracefully

Always check response status codes and handle errors appropriately in your integration.

5. Track ICR IDs

Store the returned info_capture_request_id with your internal records for tracking and follow-up actions.

FAQ

Q: What is a screening package code?

A: A screening package code identifies the specific set of checks and validations to be performed. You can create and manage screening packages in your Oho instance under Settings → Screening Package Settings. See the Setting Up Screening Packages section above for detailed instructions.

Q: Can I update an ICR after creation?

A: Yes, use the POST /api/info_capture_request/{icr_id}/action?action=update endpoint to update ICR details.

Q: What happens if I don't include email or mobile number?

A: The constituent can still be created, but they won't receive automatic notifications. You'll need to manually share the ICR link.

Q: Can I create an ICR for an existing constituent?

A: The ensure_constituent_with_icr endpoint will match existing constituents by email/name or create a new one if no match is found.

WWC Integration Guide - Working with Children Checks integration
API Reference - ICR Endpoints - Complete API specification
Authentication Guide - API authentication setup

Support

For questions or issues with ICR integration:

Check the detailed API Reference documentation
Review error messages and status codes above
Contact Oho support with your info_capture_request_id for specific requests

Version: 1.0 Last Updated: 2026-01-22 Status: Production Ready

Overview​

Setting Up Screening Packages​

What is a Screening Package?​

Creating a Screening Package​

Finding Your Package Code​

Quick Start​

1. Create Constituent with ICR​

Perform ICR Actions​

Manage Attachments​

Get Next Actions​

Common Workflows​

Workflow 1: Create and Send ICR​

Workflow 2: Resend ICR Email​

Workflow 3: Cancel ICR​

Error Responses​

401 Unauthorized​

403 Forbidden​

Best Practices​

1. Always Provide Contact Information​

2. Use Meaningful Screening Packages​

3. Set Appropriate Send Flags​

4. Handle Errors Gracefully​

5. Track ICR IDs​

FAQ​

Q: What is a screening package code?​

Q: Can I update an ICR after creation?​

Q: What happens if I don't include email or mobile number?​

Q: Can I create an ICR for an existing constituent?​

Related Documentation​

Support​