> ## Documentation Index > Fetch the complete documentation index at: https://docs.tied.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a human ownership policy revision > The account-scoped human ownership policy. Every account member can read it; only administrators can write it. POST appends an immutable revision and returns that revision with its author and timestamp. Fields omitted from POST carry forward; explicit null clears nullable wait/alert minute settings. There is no update or delete operation for past revisions. Every successful call creates the next revision, even if settings are unchanged. Administrators only. `alert_enabled` requires `alert_minutes`; `alert_minutes` must be less than `wait_trigger_minutes` when both are set. Invalid values or combinations return a field-level 422 and create no revision. A sent recipient list must contain at most 50 distinct positive integer IDs, all members of this account; a removed member in the carried-over list returns `stale_recipients` until a fresh list is supplied. Wrong value types return `invalid_params`. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/accounts/{account_id}/human_ownership_policy openapi: 3.0.4 info: title: Tied API description: >- The Tied REST API. Three families of endpoint, each with its own credential: **Application** for everything inside an account, **Platform** for provisioning accounts and users, and **Client** for acting as a contact from your own surface. version: 1.1.0 termsOfService: https://tied.com/legal contact: email: hello@tied.com license: name: MIT License url: https://opensource.org/licenses/MIT servers: - url: https://app.tied.com description: Tied cloud security: [] tags: - name: Account AgentBots description: Account-specific Agent Bots - name: Agents description: Agent management APIs - name: Canned Responses description: Pre-defined responses for common queries - name: Contacts description: Contact management APIs - name: Contact Labels description: Manage contact labels - name: Conversation Assignments description: Manage conversation assignments - name: Conversation Labels description: Manage conversation labels - name: Conversations description: Conversation management APIs - name: Custom Attributes description: Custom fields for contacts and conversations - name: Custom Filters description: Saved filters for conversations - name: Inboxes description: Communication channels setup - name: Integrations description: Third-party integrations - name: Messages description: Message management APIs - name: Profile description: User profile APIs - name: Reports description: Analytics and reporting APIs - name: Teams description: Team management APIs - name: Webhooks description: Event notification webhooks - name: Automation Rule description: Workflow automation rules - name: Help Center description: Knowledge base management - name: Contacts API description: Public contact APIs - name: Conversations API description: Public conversation APIs - name: Messages API description: Public message APIs - name: CSAT Survey Page description: Customer satisfaction survey - name: Account description: >- The authenticated user's own account — read and update account settings. Distinct from the Platform family's **Accounts**, which provisions accounts across an installation. - name: Audit Logs description: Read the account's audit trail - name: Inbox API description: Public inbox lookup by channel identifier - name: Labels description: >- Create and manage the account's labels. Applying one to a conversation or contact is a separate endpoint under those resources. - name: Macros description: >- Saved multi-step actions an agent — or an integration — can run against one or more conversations. - name: Campaigns description: Ongoing website campaigns and one-off SMS and WhatsApp sends. - name: Contact Notes description: Internal notes on a contact. Never visible to the contact. - name: Help Center Categories description: Categories group a portal's articles, one tree per allowed locale. - name: Help Center Articles description: The articles a portal publishes, and their draft and archived states. - name: Summary Reports description: Per-agent, per-team, per-inbox and per-label totals for a period, as JSON. - name: Live Reports description: Right-now queue counts. No date range — these describe the present. - name: CSAT description: >- The satisfaction ratings contacts have submitted, and the metrics computed from them. - name: Notifications description: >- The per-user notification feed, its read and snooze state, and the settings that decide what lands in it. - name: Conversation Participants description: >- The agents watching a conversation. Participants get notified about it without being assigned to it. - name: Draft Messages description: >- The unsent reply held for a conversation. Stored in Redis, one per conversation. - name: Search description: >- One search service across conversations, contacts, messages and Help Center articles. - name: Dashboard Apps description: Embedded pages that appear as a tab beside a conversation. - name: Assignment Policies description: How conversations are handed out, and which inbox uses which policy. - name: Files description: Storing a file so another endpoint can attach it. - name: Bot Flows description: >- Scripted conversation flows, their versions, and the publish and rollback that move between them. - name: Billing description: >- Credit balance, usage, invoices, spend controls and the provider-hosted payment flows. - name: AMB Templates description: >- Saved Apple Messages primitive payloads an agent can reuse from the composer. - name: AMB Onboarding description: The in-flight Apple Messages for Business registration for an account. - name: Widget Session description: Starting a widget session and reading the visitor it belongs to. - name: Widget Conversation description: The visitor's conversation and its messages. - name: Widget Context description: Campaigns, agents, labels, events and uploads for a widget session. - name: CSAT Survey description: The public, unauthenticated survey a contact answers from a link. - name: Workspace description: Scheduling and cancelling deletion of the whole workspace. - name: Widget Integrations description: Provider actions available to a visitor session in its own conversation. paths: /api/v1/accounts/{account_id}/human_ownership_policy: parameters: - in: path name: account_id schema: type: integer required: true description: The numeric ID of the account post: tags: - Account summary: Create a human ownership policy revision description: >- The account-scoped human ownership policy. Every account member can read it; only administrators can write it. POST appends an immutable revision and returns that revision with its author and timestamp. Fields omitted from POST carry forward; explicit null clears nullable wait/alert minute settings. There is no update or delete operation for past revisions. Every successful call creates the next revision, even if settings are unchanged. Administrators only. `alert_enabled` requires `alert_minutes`; `alert_minutes` must be less than `wait_trigger_minutes` when both are set. Invalid values or combinations return a field-level 422 and create no revision. A sent recipient list must contain at most 50 distinct positive integer IDs, all members of this account; a removed member in the carried-over list returns `stale_recipients` until a fresh list is supplied. Wrong value types return `invalid_params`. operationId: create-human-ownership-policy-revision requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/human_ownership_policy_payload' example: alert_enabled: false reason: Contract fixture update responses: '201': description: >- The newly appended revision. This operation does not edit an existing revision. content: application/json: schema: $ref: '#/components/schemas/human_ownership_policy_version' example: revision: 3 quiet_minutes: 90 auto_return: true wait_trigger_minutes: 120 alert_enabled: false alert_minutes: null alert_recipient_user_ids: [] return_mode: answer reason: Contract fixture update updated_at: '2026-10-21T15:22:28.402Z' updated_by: id: 47 name: Ada Admin previous_revision: 2 actor_role: administrator x-example-provenance: source: >- spec/controllers/api/v1/accounts/human_ownership_policies_controller_spec.rb, OpenAPI contracts example capture: >- Actual JSON response bodies captured from synthetic Rails request/controller responses on 2026-10-21. Two policy revisions were seeded before GET current, GET history, and POST; POST returned revision 3. No provider calls are made on these routes. scrubbed: true '400': description: >- The request presented both a Devise Token Auth session credential and an api_access_token. The request is refused before the action runs. content: application/json: schema: type: object required: - error properties: error: type: object required: - code properties: code: type: string enum: - multiple_credentials additionalProperties: false additionalProperties: false example: error: code: multiple_credentials x-example-provenance: source: >- spec/controllers/api/v1/accounts/human_ownership_policies_controller_spec.rb, mixed-credential contract regression capture: >- Actual JSON response captured from an authenticated account administrator request carrying both a Devise Token Auth access-token header and an agent-bot api_access_token header. CredentialCombinationGuard returned HTTP 400 before the action; the existing policy revision remained unchanged. No credential values are included. scrubbed: true '401': description: >- Unauthenticated or account is not accessible to the caller. Devise authentication responses may use an `errors` array; account access denials use `error`. content: application/json: schema: oneOf: - $ref: '#/components/schemas/error_message' - type: object required: - errors properties: errors: type: array items: type: string '402': description: >- The account trial has expired and the workspace is locked. Restore billing before creating a policy revision. content: application/json: schema: type: object required: - error - message properties: error: type: string enum: - trial_expired_locked message: type: string example: error: trial_expired_locked message: >- This workspace trial has ended. Restore billing from the billing page to continue. x-example-provenance: source: >- spec/controllers/api/v1/accounts/human_ownership_policies_controller_spec.rb, locked account POST contract regression capture: >- Actual JSON response captured from an authenticated administrator POST to /api/v1/accounts/{account_id}/human_ownership_policy with custom_attributes.subscription_status set to trial_expired_locked. The inherited account controller returned Billing::TrialLock.refusal_payload and created no policy revision. scrubbed: true '403': description: Caller is an account member but is not an administrator. content: application/json: schema: type: object properties: error: type: string message: type: string '422': description: >- Field-level policy validation or stale carried-over recipients; malformed field types return invalid_params. No revision is created. content: application/json: schema: oneOf: - type: object required: - error - message properties: error: type: string enum: - invalid - stale_recipients message: type: string - type: object required: - error properties: error: type: string enum: - invalid_params security: - userApiKey: [] components: schemas: human_ownership_policy_payload: type: object additionalProperties: false properties: quiet_minutes: type: integer minimum: 15 maximum: 10080 description: >- How long the agent stays quiet after a teammate replies; 15 minutes through 7 days. Default 720. auto_return: type: boolean description: Whether the agent automatically takes the conversation back. wait_trigger_minutes: type: integer minimum: 5 maximum: 1440 nullable: true description: >- Optional customer-wait trigger, 5–1440 minutes; null disables it. Inert when auto_return is false. alert_enabled: type: boolean description: >- Whether to alert selected account members when the customer has waited. alert_minutes: type: integer minimum: 5 maximum: 1440 nullable: true description: >- Optional alert delay, 5–1440 minutes; null disables it. Required when alert_enabled is true and must be less than wait_trigger_minutes when both are set. alert_recipient_user_ids: type: array items: type: integer minimum: 1 description: >- Array of positive user IDs that belong to this account. At most 50 distinct members are stored; repeated IDs are normalized to one sorted entry. return_mode: type: string enum: - answer - answer_with_follow_up - escalate description: Agent behavior when it returns. reason: type: string nullable: true maxLength: 500 description: Optional change reason; at most 500 characters. human_ownership_policy_version: allOf: - $ref: '#/components/schemas/human_ownership_policy' - type: object required: - previous_revision - actor_role properties: previous_revision: type: integer nullable: true description: Revision this version follows; null for revision 1. actor_role: type: string enum: - administrator - system error_message: type: object description: >- The shape returned by `render_unauthorized`, `render_not_found_error` and `render_could_not_create_error`. properties: error: type: string description: A single human-readable message. example: Resource could not be found required: - error human_ownership_policy: type: object required: - revision - quiet_minutes - auto_return - wait_trigger_minutes - alert_enabled - alert_minutes - alert_recipient_user_ids - return_mode - reason - updated_at - updated_by properties: revision: type: integer description: >- Current revision number; 0 means the account has not saved a revision. quiet_minutes: type: integer minimum: 15 maximum: 10080 description: >- How long the agent stays quiet after a teammate replies; 15 minutes through 7 days. Default 720. auto_return: type: boolean description: >- Whether the agent automatically takes the conversation back. Default true. wait_trigger_minutes: type: integer minimum: 5 maximum: 1440 nullable: true description: >- Optional customer-wait trigger, 5–1440 minutes; null disables it. Default null. Inert when auto_return is false. alert_enabled: type: boolean description: >- Whether to alert selected account members when the customer has waited. Default false. alert_minutes: type: integer minimum: 5 maximum: 1440 nullable: true description: >- Optional alert delay, 5–1440 minutes; null disables it. Default null. Required when alert_enabled is true and must be less than wait_trigger_minutes when both are set. alert_recipient_user_ids: type: array maxItems: 50 uniqueItems: true items: type: integer minimum: 1 description: >- Up to 50 distinct IDs of members of this account. Stored sorted and unique. Default empty list. return_mode: type: string enum: - answer - answer_with_follow_up - escalate description: >- Agent behavior when it returns: answer (default), answer_with_follow_up, or escalate. reason: type: string nullable: true maxLength: 500 description: >- Optional change reason; at most 500 characters and must not contain a NUL byte. Default null. updated_at: type: string format: date-time nullable: true description: Time the current revision was created; null for revision 0. updated_by: type: object nullable: true description: Author if still a member of the account, otherwise null. required: - id - name properties: id: type: integer description: ID of a member of this account. name: type: string description: Display name of this account member. securitySchemes: userApiKey: type: apiKey in: header name: api_access_token description: >- This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.