Account and users

Your account's settings and the people who use the dashboard. These routes replace v2's earlier account_settings resource.

The account entity

{
  "id": 4127,
  "name": "Example Builders",
  "party_name": "Subcontractors",
  "party_name_singular": "Subcontractor",
  "project_name": "Jobs",
  "certificate_holder_name": "Example Builders LLC",
  "certificate_holder_address1": "1 Plaza",
  "certificate_holder_address2": null,
  "certificate_holder_city": "Austin",
  "certificate_holder_state": "TX",
  "certificate_holder_postal_code": "78701",
  "contact_limit_override": null,
  "contact_delay_override": null,
  "require_approval_override_date": true,
  "require_approval_override_notes": false,
  "...": "every setting listed below"
}

Settings of features your account does not use are present with an empty or default value.

party_name, party_name_singular and project_name are read-only: the nouns your dashboard uses for parties and projects (set by party_name_override and project_name_override). Use them to label your own UI; the API itself always says parties and projects.

GET /account

The account entity.

PATCH /account

Updates the settings you send and leaves the rest alone. These are the settings the dashboard's Settings page lets an account user change:

name, project_name_override, party_name_override, note_to_party, request_email_note, individual_name_override, note_to_individuals, individual_email_note, project_completion_retention_days, party_assignment_mode (once a User custom field exists), tag_name_override, triage_queue_name_override, triage_entry_gate_mode, triage_readd_on_resubmission, collect_w9, enable_party_notes, certificate_holder_name, certificate_holder_address1, certificate_holder_address2, certificate_holder_city, certificate_holder_state, certificate_holder_postal_code, cert_copy_address, cert_copy_all_submissions, cert_copy_show_external_id, apply_umb_to_gl_limits, apply_umb_to_auto_limits, contact_limit_override, contact_delay_override, validate_certificate_holder, validate_certificate_holder_address, workday_notifications_only, show_vendor_contact_information, enable_editing_of_vendor_addresses, enable_expiration_reminders.

Read-only here: require_mfa, require_approval_override_date and require_approval_override_notes are served by GET /account but can be changed only by a person on the dashboard's Settings page, so a key can never turn off two-factor sign-in or loosen the approval-override policy. Sending the value already served is accepted and changes nothing (so a GET body can be sent back as is); any other value is 422 validation_failed naming the field, and nothing is changed. Feature switches that only HoundDog staff can turn on are not settable here either. A setting that belongs to a feature your account does not use: changing it is 403 feature_disabled naming the field, and sending the stored value back is accepted. The labels (party_name_override, project_name_override, tag_name_override, individual_name_override, triage_queue_name_override) and triage_entry_gate_mode, party_assignment_mode and project_completion_retention_days take only the choices the dashboard's Settings page offers (listed in the contract); any other new value is 422 validation_failed naming the field, while sending back the value already stored is always accepted, an older label no longer offered on the dashboard included. Side effect: changing a setting that affects compliance (for example validate_certificate_holder, validate_certificate_holder_address, apply_umb_to_gl_limits, apply_umb_to_auto_limits) rechecks every active party in the background, which can change statuses, fire their events and webhooks, and start requests.

Response 200 with the entity. Errors: 403 feature_disabled (a changed setting of a feature your account does not use); 422 validation_failed (an invalid value, a value outside a setting's choices, or one of the three read-only settings above sent with a value other than the one served). Event: Account Settings Updated, recorded with your key.

The user entity

{ "id": 301, "email": "[email protected]", "first_name": "Sam", "last_name": "Ortiz", "account_status": "User", "invitation_pending": false }

account_status is the user's tier: Admin, User or Agent. invitation_pending is true until the invited person sets up their login.

GET /users

The account's users in the collection envelope.

POST /users

Invites a user by email. Body: email (required, not already in use), first_name, last_name, account_status (Admin, User or Agent; defaults to User). The invitee receives the invitation email. Event: User Added. Response 201. Errors: 422 validation_failed (an email that is not a plain email address, an email already in use, an unknown account_status). A user's email cannot be changed through the API.

A key can invite an Admin, so only users who hold the Manage API Access permission can create keys (Authentication).

PATCH /users/:id

Updates first_name, last_name and account_status. Event: User Updated, recorded with your key, its details holding the changed fields. Response 200. Errors: 422 validation_failed (an unknown account_status).

DELETE /users/:id

Removes the user as the dashboard does: an invitation that was never accepted is deleted; a user who has used the account is deactivated (kept for the history), can no longer sign in, and no longer appears in GET /users. Event: User Removed, recorded with your key. Response 204.