Apricot API Endpoints (v1.0)

Checks whether the Apricot service is available. There is currently no scenario in which this endpoint returns a 2XX response - a healthy service responds with a 418 status and an empty body.

Retrieves a list of all users in your Apricot instance. Pagination (page[size]) is required; filtering and sorting are optional.

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, 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 is optional. If omitted, a random placeholder value is auto-generated; complexity requirements are only checked when a password value is supplied.
• User type determines permissions
• Only an Administrator (or Super User) can create another Admin user; otherwise the request fails with a 400
• Org-level seat count limits (Administrator/Standard) are enforced before creation; exceeding them fails with a 400
• When the organization has site_admins_enabled and the new user is not an Admin, a non-empty site_links array is required or the request fails with a 400

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
• org_id - Your organization ID
• username - Your login username
• user_type - Your role/permissions level
• name_first, name_middle, name_last - Your full name
• active - Whether your account is active
• 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)

Important notes:

• Returns 404 if the token owner's own user record can't be resolved (same lookup path as GET /users/{id})

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
• Returns 400 if bonterra_auth_id is missing
• User can belong to multiple organizations with different roles
• Only organizations that are active (org_active) and have a real org_id (> 0) are ever returned; inactive organizations and the synthetic org_id=0 super-user row are always excluded from orgs
• If the caller (the authenticated requester, not the target bonterra_auth_id user) belongs to a real organization, the results are scoped to that organization only - the caller cannot see the target user's memberships in other organizations
• is_super_user being true does not imply an empty orgs array - a super user with real active organization memberships will still have them listed

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)
• Pagination parameters (page[size] is required); sorting and filtering are optional
• 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 (used for login; there is no separate email field)
• User's full name (first and last)
• User's user_type (e.g. Administrator, Standard User, Guest), which determines permissions level - there is no separate scalar role field
• Active status
• Last login information
• User metadata

Inactive users are always excluded from the results; there is no way to opt in to seeing them.

Common use cases:

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

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

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)
• Site ID (required) - the program must be linked to an existing site
• Program description (optional but recommended)
• Access token with apricot.create scope
• Organization Admin or Site Admin permissions

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:

• The API does not enforce unique program names
• New programs are always created as active; the active field is ignored/overridden on creation
• Requires Admin or Site Admin permissions; other users receive a 403 Forbidden
• 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
• mod_time / mod_user - Last modification timestamp and user
• 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 program to update is determined solely by the id URL path parameter; any id/type values in the request body are ignored
• 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 the same program object as GET /apricot/programs/{id}, scoped to the caller's intake-specific permissions rather than their general program-access permissions. It is intended for Bonterra Connect intake and referral workflows that need to look up an Apricot program's details before creating a record in it.

When to use it:

• Look up an Apricot program's details as part of a Connect intake/referral workflow
• Verify a program exists and check its active status before creating a referral record
• Retrieve program details when the caller's access token is scoped for intake rather than general program access

What you'll need:

• Program ID from Apricot
• Access token scoped for intake access

What you'll get back: The identical program object returned by GET /apricot/programs/{id} (same id, name, description, active status, referral settings, and other program attributes). There is no separate "intake format" - the response shape is identical.

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

vs. GET /programs/{id}:

• This endpoint: Same response shape, but authorizes against intake-scoped permissions instead of general program-access permissions, and does not record the "program viewed" audit event/record action that GET /programs/{id} records
• GET /programs/{id}: Standard program details, authorized against general program-access permissions

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)
• Pagination parameters (page[size] is required); sorting and filtering are optional
• 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 (used for login; there is no separate email field)
• User's full name (first and last)
• User's user_type (e.g. Administrator, Standard User, Guest), which determines permissions level - there is no separate scalar role field
• Active status
• Last login information
• User metadata

Inactive users are always excluded from the results; there is no way to opt in to seeing them.

Common use cases:

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

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's attributes and permission sets. 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)
• Optional: New program name and description (if name is omitted, the copy inherits the source program's exact name)
• Access token with apricot.create scope
• Organization Admin or Site Admin permissions

What gets copied:

• Program-level attributes and settings (name, description, contact info, referral settings, etc.), overridden by anything provided in the request body
• Permission sets (and their assigned users) - always copied, this cannot be opted out of

What does NOT get copied:

• Forms - Programs have no form association to copy
• Actual records (data)
• Record-level attachments or files
• Historical data or audit logs

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 API does not enforce unique program names; omitting name silently produces a duplicate name
• Records from the source program are NOT copied
• Forms are not copied or associated in any way; Programs have no form association
• Permission sets are always copied along with their members; you cannot opt out

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 the caller has intake-scoped access to.

Unlike GET /apricot/programs, which returns 200 with an empty array when there are no matching programs, this endpoint returns 404 when there are no intake-eligible programs.

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

Filtering: filter[field_<id>]=value performs a SQL LIKE match on that field, where <id> is the field's numeric ID (e.g. field_2002, discoverable via GET /apricot/forms/{id}/fields) - not the field's label. The value is passed directly to LIKE, so it supports % as a wildcard (e.g. filter[field_2002]=John% matches values starting with "John"); a value with no % matches only that exact string.

PII filtering and field metadata:

• pii_filter=true removes PII fields (name, address, email, phone, SSN, photo/signature, etc.) from every record in the response.
• include_field_metadata=true adds a meta.field_metadata map (keyed by field_<id>, each entry containing id, label, field_type_id, field_type_name) describing the fields present in the response.

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
• Do NOT set Content-Type header manually when using multipart/form-data
• Programs array is optional but recommended for multi-program forms

How the multipart/form-data body is actually parsed (important): The multipart parser does not look for a field named data - it has no special handling for any field name. For every non-file field it receives, it attempts JSON.parse(value); if that succeeds, the entire request body is replaced with the parsed result (not merged), regardless of what the field was named. Only if JSON.parse fails does the parser fall back to setting that one key (req.body[key] = value). This means:

• You can technically name the JSON field anything (not just data) and it will work.
• If you send more than one JSON-parseable field, only the last one processed wins - it silently overwrites the earlier one, with no error or warning.
• For predictable results, send exactly one field containing the JSON record payload (conventionally named data) alongside your file fields.

What it does: Retrieves a single record by its unique identifier. Returns the complete record including all field values, metadata, attachment information, timestamps, and relationships.

When to use it:

• View detailed information for a specific client or record
• Retrieve current record data before updating (recommended before PUT)
• Check if a record exists and is accessible
• Get attachment metadata for files associated with the record
• Fetch related record information via links
• Verify successful record creation

What you'll need:

• Record ID (from POST /records response or GET /records list)
• Access token with apricot.read scope

What you'll get back: A record collection object ({meta, data: [...]}) whose data array contains exactly one record, with:

• id - The unique record identifier
• type - Resource type (always "records")
• attributes - All field values including:
  • form_id - The form this record belongs to
  • programs - Array of program IDs
  • Dynamic fields (field_1001, field_2_first, etc.)
  • Attachment metadata (filename, size, URL) for any file fields
  • creation_time, mod_time - Timestamps
• links - Navigation URLs (self, form, related records)

Understanding the Response:

• Field values match the field IDs from the form structure
• Attachment fields contain file metadata objects with download URLs
• Empty/null fields indicate no value was set
• Timestamps are in ISO 8601 format

Important notes:

• Returns 404 if the record doesn't exist
• Returns 403 if the record exists but you don't have permission to view it
• Use this before PUT to get current values and avoid overwriting data
• Attachment fields show metadata but don't include file contents
• Use GET /records/{id}/attachment/{field_id} to download actual files
• Links section provides URLs to related resources

What it does: Updates an existing record with new field values. You can update one field or multiple fields in a single request. Fields not included in the request remain unchanged.

When to use it:

• Update client or participant information
• Change record status, category, or other field values
• Modify specific fields without affecting others
• Correct or update existing data
• Mark records as active/inactive

What you'll need:

• Record ID (from GET /records or POST /records response)
• Field values to update (only include fields you want to change)
• Access token with apricot.update scope
• Best practice: GET the record first to see current values

What you'll get back: Updated record object with all field values (not just the ones you updated)

Two Update Strategies:

Strategy 1: Partial Update (Recommended for most cases) Only send the fields you want to change. Other fields remain unchanged.

• ✅ Simpler - less data to send
• ✅ Faster - smaller payload
• ⚠️ Risk: If another update happened between your GET and PUT, those changes are preserved

Strategy 2: Full Update (Safest for critical data) GET the record first, modify the fields you want, then PUT the complete attributes object.

• ✅ Safer - you see exactly what you're changing
• ✅ Prevents accidental overwrites
• ⚠️ Slower - requires two API calls

Important notes:

• Only fields in your request will be updated
• Omitted fields keep their current values
• Cannot update id, creation_time, or other system fields
• Use GET first to retrieve current values (recommended)
• Returns 404 if the record doesn't exist
• Returns 400 if attributes.form_id doesn't match the record's current form - records cannot be moved between forms via this endpoint. form_id in the body must equal the record's existing form_id; a different value is rejected as an error, not treated as a move.
• To update attachments, use POST /records/{id}/attachment/{field_id}

Common Issues:

"Required field missing" error:

• Cause: Form has required fields that are empty
• Solution: Include all required fields in your update, or use metadata.uiRequirementsToBypass

Accidentally clearing fields:

• Problem: Sending null or empty string clears the field
• Solution: Only include fields you explicitly want to change