Consumer Experiences

Surface what a consumer needs to do next. Consumer Experiences enables developers to build timely, personalized experiences in their own apps by returning the actions a consumer or business contact needs to complete. Use these resources to show actionable items, reduce missed deadlines, and keep consumers on track with their benefits and accounts. [Add one line on any other APIs in this section.]

Core Experience Services

1. Tasks API

The Tasks API returns the visible, priority-ordered task list for a person.

• Priority Ordering: Tasks are ordered by display priority, highest first. Tasks with equal priority are ordered by metadata.created_utc, oldest first.
• Person Resolution: A supplied person_id takes precedence. Otherwise, the caller’s bp_person claim is used. If neither is present, the request returns 400.
• Type Filtering: Narrow results with the repeatable task_type parameter (for example, ?task_type=REPAYMENTS_DUE&task_type=RECEIPTS_NEEDED). Omit it to return all visible task types.
• Protected Visibility: Authorization denials return 404 instead of 403, so the existence of persons outside the caller’s scope is never disclosed.
• Implementation Note: Consumer and BusinessContact tokens must include the bp_business claim. Requests without it return 401.

Integration Standards

Security & Authentication

Consumer experience operations require OAuth scopes to ensure data privacy:

• [scope name]: Required for retrieving tasks.

Operational Consistency

• Identifier Standards:person_id uses UUID format.
• Task Type Format: Task types use UPPER_SNAKE_CASE, which is canonical for requests and responses. PascalCase values (for example, RepaymentsDue) are accepted for backward compatibility only. Unrecognized values return 400. [Add the full list of supported task types.]
• Troubleshooting: Use the optional X-Request-Id header (alphanumeric or hyphen, up to 36 characters) across all requests for cross-system correlation and error logging.
• Error Format: Error responses include type, title, status, detail, instance, errors, and validation_errors.

Global Error Reference