Bonterra API Endpoints (v1.0)

Retrieves a list of all users in your Apricot instance. Supports pagination, filtering, and sorting.

Common use cases:

• List all users for administrative purposes
• Export user directory
• Find users by name or email using filters
• Sync user list with external systems

Creates a new user account in Apricot. Requires username, password, first name, last name, and user type.

Common use cases:

• Add new team members programmatically
• Bulk import users from external systems
• Automated user provisioning

Important notes:

• Username must be unique (typically an email address)
• Password must meet complexity requirements
• User type determines permissions

What it does: Retrieves the profile information for the currently authenticated user based on the access token. This is a self-service endpoint that returns details about "you" (the token owner) without needing to know your user ID.

When to use it:

• Get your own user profile on login
• Display current user information in UI
• Verify authentication and user identity
• Check your own permissions and roles
• Build "My Profile" or "Account Settings" pages
• Validate which Apricot instance you're connected to

What you'll need:

• Valid access token (identifies you automatically)
• No user ID required - uses token to determine identity

What you'll get back: Your complete user profile including:

• id - Your unique user ID
• username - Your login username
• email - Your email address
• name_first and name_last - Your full name
• role - Your role/permissions level
• active - Whether your account is active
• programs - Programs you have access to
• last_login - Your last login timestamp
• Custom user attributes

Use cases:

• "Who am I?" - Identity verification after authentication
• Displaying logged-in user name in application header
• Checking if you have required permissions before actions
• Personalizing the user experience based on your profile

vs. GET /users/{id}:

• This endpoint: Gets YOUR info (token-based, no ID needed)
• GET /users/{id}: Gets ANY user's info (requires user ID and admin permissions)

Retrieves all Apricot organizations that a Bonterra Auth user is linked to. This endpoint is used for authorization purposes by Account and Impact Hub services.

Purpose:

• Query linked Apricot users for a given Bonterra Auth user ID
• Retrieve organization membership and user details
• Support authorization decisions across services

Personas:

• Account service (Authorization Code Grant & Client Credentials Grant)
• Impact Hub service (Authorization Code Grant & Client Credentials Grant)

Important notes:

• Returns empty array if user has no organizations (still 200 status)
• Returns 404 only when the Bonterra Auth user ID doesn't exist
• User can belong to multiple organizations with different roles

What it does: Retrieves a list of all users who have been granted access to a specific program. This helps you manage program-level permissions and understand who can view/edit data within a program.

When to use it:

• Audit which users have access to a program
• Manage program-level user permissions
• Verify user access before assigning work
• Build user access reports and matrices
• Onboard new staff to see team composition
• Identify users to notify about program changes
• Export user lists for program documentation

What you'll need:

• Program ID (get from GET /apricot/programs)
• Optional: Pagination, sorting, and filtering parameters
• Access token with apricot.read scope

What you'll get back: Array of user objects with access to this program, each containing:

• User ID, username, email
• User's full name (first and last)
• User role and permissions level
• Active status
• Last login information
• User metadata

Common use cases:

• Access Control: "Who can see this program's data?"
• Team Management: List all case workers in the Housing program
• Notifications: Get emails of users to notify about program updates
• Reporting: Generate staff rosters per program
• Troubleshooting: Verify why a user can/cannot access program data

Filtering & Pagination:

• Filter by active status, role, or name
• Sort by name, last login, or role
• Paginate large user lists

Note: This returns users with explicit program access. System administrators may have access to all programs without being explicitly listed.

What it does: Retrieves the metadata value associated with a specific key for a user. User metadata allows you to store custom key-value pairs for users, enabling extensibility beyond standard user fields.

When to use it:

• Retrieve custom user preferences or settings
• Get integration-specific data stored for a user
• Access user configuration from external systems
• Read custom attributes not in the standard user schema
• Check feature flags or permissions stored as metadata
• Retrieve API-specific tracking information

What you'll need:

• User ID
• Metadata key name (e.g., "preferred_language", "external_id", "notification_settings")
• Access token with apricot.read scope

What you'll get back: The metadata value for the specified key, which can be:

• String values (e.g., "en-US", "enabled")
• Numeric values
• JSON objects for complex data
• Timestamps or dates

Common metadata keys:

• external_system_id - ID from integrated system
• preferred_language - User's language preference
• notification_preferences - Communication settings
• last_sync_time - Integration sync timestamp
• custom_permissions - Role-based access flags

What it does: Creates or updates a metadata key-value pair for a user. If the key already exists, its value is updated. If the key doesn't exist, it's created. This allows you to store custom data associated with users.

When to use it:

• Store custom user preferences or settings
• Save integration-specific identifiers
• Maintain external system mappings
• Store feature flags or permissions
• Save user-specific configuration
• Track custom attributes not in standard schema
• Persist API-related state information

What you'll need:

• User ID
• Metadata key name (string identifier)
• Metadata value (can be string, number, boolean, or JSON object)
• Access token with apricot.update scope

What you'll get back: Confirmation of the updated/created metadata including:

• The key that was updated
• The new value
• User ID
• Timestamp of the update

Best practices:

• Use descriptive, namespaced key names (e.g., "salesforce_contact_id" not "id")
• Keep values reasonably sized (avoid storing large documents)
• Use consistent data types for each key across users
• Document your metadata schema for your team

Common use cases:

• Storing external system IDs for bi-directional sync
• Saving user preferences that aren't in standard fields
• Tracking integration-specific timestamps
• Maintaining custom permissions or feature access

What it does: Permanently deletes a metadata key-value pair for a specific user. Once deleted, the metadata cannot be recovered unless you re-create it with a PUT request.

When to use it:

• Remove outdated custom user settings
• Clear integration-specific data that's no longer needed
• Delete temporary flags or markers
• Clean up test metadata
• Remove deprecated custom attributes
• Clear cached or stale integration data

What you'll need:

• User ID
• Metadata key name to delete
• Access token with apricot.delete scope

What you'll get back: Confirmation that the metadata was deleted, including:

• Success status
• The key that was deleted
• User ID

Important notes:

• This is a permanent deletion - the metadata cannot be recovered
• Deleting a non-existent key will typically return a success response
• Only the specified key is deleted; other metadata for the user remains intact
• Consider using PUT with an empty/null value if you want to preserve the key structure

Common scenarios:

• Removing external system mappings after integration is disabled
• Clearing temporary feature flags after testing
• Deleting cached data that should be refreshed
• Cleaning up user-specific integration state

Retrieves a list of all programs in your Apricot instance. Programs are used to organize records and users by service type or department.

Common use cases:

• List all programs for administrative purposes
• Get program IDs for filtering records
• Display programs in UI dropdowns
• Export program configurations

What it does: Creates a new program in your Apricot instance. Programs are the top-level organizational structure used to group related forms, records, and users. Each program typically represents a distinct service area, grant-funded initiative, or department.

When to use it:

• Set up a new service program or initiative
• Create a program for a new grant or funding source
• Establish a departmental data collection area
• Organize data for different service populations
• Separate data by geographic region or location
• Create programs for different fiscal years

What you'll need:

• Program name (required, must be unique)
• Program description (optional but recommended)
• Active status (defaults to true)
• Optional: Form IDs to associate with this program
• Optional: User IDs to grant access to this program
• Access token with apricot.create scope

What you'll get back: The newly created program object including:

• Unique program ID (use this for record creation)
• All provided attributes
• Creation timestamp
• Default settings for new programs

Important notes:

• Program names must be unique within your Apricot instance
• New programs start as active by default
• You can add forms and users to the program later
• Programs cannot be deleted via API (deactivate instead)

Common program types:

• Service delivery programs (e.g., "Housing Assistance", "Job Training")
• Grant-funded initiatives (e.g., "2025 SAMHSA Grant")
• Administrative divisions (e.g., "Northern Region", "Youth Services")
• Time-based programs (e.g., "FY2025 Emergency Relief")

What it does: Retrieves detailed information about a specific program. Programs in Apricot are organizational containers that group related forms, records, and users together, representing distinct service areas or organizational divisions.

When to use it:

• Get details about a specific program
• Check if a program is active before creating records
• Retrieve program metadata and configuration
• Verify program names and descriptions
• Build program-specific dashboards or reports
• Validate program IDs before assigning records

What you'll need:

• Program ID (get from GET /apricot/programs)
• Access token with apricot.read scope

What you'll get back: Complete program object including:

• id - Unique program identifier
• name - Program name (e.g., "Youth Services", "Housing Assistance")
• description - Program description
• active - Whether the program is currently active
• form_ids - Array of form IDs associated with this program
• user_ids - Array of user IDs who have access to this program
• created_at - When the program was created
• updated_at - Last modification timestamp
• Custom program-level fields and metadata

Program hierarchy: Programs can contain multiple forms, and each form can contain multiple records. Understanding the program structure is essential for proper data organization.

What it does: Updates an existing program's properties. You can modify the program name, description, active status, and other program-level attributes. This operation performs a partial update, so you only need to include the fields you want to change.

When to use it:

• Change a program's name or description
• Activate or deactivate a program
• Update program settings or configuration
• Modify program metadata
• Update program associations (forms, users)
• Correct program information

What you'll need:

• Program ID
• Fields you want to update (only send fields that should change)
• Access token with apricot.update scope

What you'll get back: The complete updated program object with all fields, including:

• All attributes (both changed and unchanged)
• Updated timestamp showing when the modification occurred
• Confirmation of the new values

Important notes:

• This is a partial update - only include fields you want to change
• The id field in the request body must match the URL path parameter
• Changing a program to inactive may affect record creation
• Some fields may be read-only depending on your permissions

Common update scenarios:

• Deactivating a program at the end of a grant period
• Renaming a program for clarity
• Updating program descriptions as services evolve
• Modifying program settings for new requirements

What it does: Retrieves program configuration optimized for Bonterra Connect's intake process. This endpoint returns program information in a format specifically designed for cross-product integration, particularly for referral and intake workflows between Connect and Apricot.

When to use it:

• Integrate Apricot programs with Bonterra Connect
• Set up cross-system referral workflows
• Configure Connect intake forms that create Apricot records
• Build unified intake experiences across products
• Synchronize program configurations between systems
• Enable seamless referrals from Connect to Apricot programs

What you'll need:

• Program ID from Apricot
• Access token with cross-product permissions
• Connect integration enabled for your organization

What you'll get back: Program object with Connect-specific configuration:

• Program ID, name, and description
• Intake-relevant program settings
• Form associations for intake processes
• Field mappings for Connect-to-Apricot data flow
• Program active status
• Integration-specific metadata

Integration scenario:

1. Connect receives a referral or intake request
2. Connect queries this endpoint to get Apricot program details
3. User selects which Apricot program to refer client to
4. Connect creates a record in Apricot using the program configuration
5. Client data flows from Connect intake to Apricot program

vs. GET /programs/{id}:

• This endpoint: Optimized for Connect integration (specific format)
• GET /programs/{id}: Standard program details (general use)

Note: This is a specialized endpoint for Bonterra product integration. If you're not integrating with Connect, use the standard GET /programs/{id} endpoint instead.

What it does: Retrieves a list of all users who have been granted access to a specific program. This helps you manage program-level permissions and understand who can view/edit data within a program.

When to use it:

• Audit which users have access to a program
• Manage program-level user permissions
• Verify user access before assigning work
• Build user access reports and matrices
• Onboard new staff to see team composition
• Identify users to notify about program changes
• Export user lists for program documentation

What you'll need:

• Program ID (get from GET /apricot/programs)
• Optional: Pagination, sorting, and filtering parameters
• Access token with apricot.read scope

What you'll get back: Array of user objects with access to this program, each containing:

• User ID, username, email
• User's full name (first and last)
• User role and permissions level
• Active status
• Last login information
• User metadata

Common use cases:

• Access Control: "Who can see this program's data?"
• Team Management: List all case workers in the Housing program
• Notifications: Get emails of users to notify about program updates
• Reporting: Generate staff rosters per program
• Troubleshooting: Verify why a user can/cannot access program data

Filtering & Pagination:

• Filter by active status, role, or name
• Sort by name, last login, or role
• Paginate large user lists

Note: This returns users with explicit program access. System administrators may have access to all programs without being explicitly listed.

What it does: Creates a copy (clone) of an existing program, duplicating its structure, forms, and configuration. This is useful when you need to create a new program with similar settings to an existing one, saving time compared to manually recreating everything from scratch.

When to use it:

• Create a new program based on an existing template
• Replicate a program structure for a new grant year or funding cycle
• Establish similar programs for different geographic regions
• Set up pilot programs based on existing successful programs
• Create backup copies of program configurations
• Standardize program structure across your organization

What you'll need:

• Source program ID (the program to copy from)
• New program name (must be unique)
• Optional: New program description and settings
• Access token with apricot.create scope

What gets copied:

• Program structure and configuration
• Associated forms (references, not duplicates)
• Form field configurations
• Program-level settings and metadata
• User access permissions (optionally)

What does NOT get copied:

• Actual records (data)
• Record-level attachments or files
• Historical data or audit logs
• Program-specific customizations that aren't transferable

What you'll get back: The newly created program object including:

• New unique program ID
• All copied attributes and settings
• Creation timestamp
• Confirmation of successful duplication

Important notes:

• The new program name must be unique
• Records from the source program are NOT copied
• Form associations are copied, but forms themselves are shared (not duplicated)
• You may need to adjust user access permissions after copying

Common scenarios:

• "Youth Services 2024" → "Youth Services 2025"
• "Regional Program - North" → "Regional Program - South"
• "Pilot Housing Assistance" → "Housing Assistance Program"
• Template programs for standardizing across departments

Get a list of all Apricot Programs for Connect Intake

Retrieves all records for a specific form. Use this endpoint to fetch a list of records that belong to a particular form. Results can be paginated.

Common use cases:

• List all client intake records
• Export form data for reporting
• Sync records with external systems

What it does: Creates a new record in the specified form. This endpoint supports three content types for different use cases, including the ability to create a record with file attachments in a single request.

When to use it:

• Add a new client intake record
• Create records programmatically from external systems
• Bulk import data into Apricot
• Create records with initial file attachments (using multipart/form-data)

What you'll need:

• Form ID (required - get this from GET /apricot/forms)
• Field values matching your form's field IDs (field_1001, field_1002, etc.)
• For attachments: Files to upload (PDF, DOCX, images, etc.)
• Access token with apricot.create scope

What you'll get back: Newly created record with ID and all field values including attachment metadata if files were uploaded

Three Content Type Options:

1. application/json (Most common) Use for creating records without files. Simple JSON body with field values.

2. application/vnd.api+json (JSON API format) Use if your application follows JSON API specification.

3. multipart/form-data (For records with attachments - Option 1) Use when creating a new record AND you have files ready to attach immediately. This is the "Option 1" approach for working with attachments.

Two Approaches for Attachments:

Option 1: Create Record with Attachments (this endpoint with multipart/form-data)

• ✅ Atomic operation - record and files created together
• ✅ Best for: New records with initial attachments
• ✅ All data and files ready at once
• Use multipart/form-data content type
• See examples below

Option 2: Add Attachment to Existing Record

• Use POST /apricot/records/{id}/attachment/{field_id}
• Best for adding files to existing records
• See that endpoint for details

Field Naming Patterns: Field IDs follow specific patterns based on field type:

• Simple fields: field_1001, field_1002
• Name fields: field_2_first, field_2_last
• Address fields: field_99_line1, field_99_city, field_99_state, field_99_zip
• Attachment fields: field_827, field_950 (uploaded as files in multipart/form-data)

Important notes:

• The form_id parameter is required (query parameter or in attributes)
• Field IDs are specific to each form's configuration
• Use GET /apricot/forms/{id} to discover available fields and their IDs
• For multipart/form-data: include 'data' field with JSON, then add file fields
• Do NOT set Content-Type header manually when using multipart/form-data
• Programs array is optional but recommended for multi-program forms