Humaans (Humaans v0.6.0)

Copy Markdown View Source

A HTTP client for the Humaans API.

This library provides an interface to the Humaans API, allowing you to manage people, companies, bank accounts, compensations, timesheet entries, and more. It follows a modular design where the main Humaans module serves as the entry point for creating clients, while specific resource modules handle operations for each resource type.

Humaans API Documentation

Architecture

The library follows a layered architecture:

  • Humaans - Main module that creates configured client instances
  • Resource modules (People, Companies, etc.) - Handle operations specific to each resource type
  • HTTP client - Abstracts the HTTP communication details in a configurable manner

Configuration Options

When creating a client with Humaans.new/1, you can configure:

  • :access_token - Your Humaans API access token (required)
  • :base_url - The base URL for API requests (defaults to "https://app.humaans.io/api")
  • :http_client - The HTTP client module to use (defaults to Humaans.HTTPClient.Req)
  • :req_options - Keyword list merged into the default Req client config (e.g. [connect_options: [timeout: 30_000], retry: :transient]). Has no effect when :http_client is overridden.

Examples

# Create a default client
client = Humaans.new(access_token: "some-access-token")

# Create a client with custom base URL
client = Humaans.new(
  access_token: "some-access-token",
  base_url: "https://custom-instance.humaans.io/api"
)

# Create a client with custom HTTP client
client = Humaans.new(
  access_token: "some-access-token",
  http_client: MyCustomHTTPClient
)

# Tune timeouts and retries on the default Req client
client = Humaans.new(
  access_token: "some-access-token",
  req_options: [connect_options: [timeout: 30_000], retry: :transient]
)

# Make API calls
{:ok, people} = Humaans.People.list(client)
{:ok, person} = Humaans.People.retrieve(client, "123")
{:ok, companies} = Humaans.Companies.list(client)

# Create a new person
person_params = %{
  "firstName" => "Jane",
  "lastName" => "Doe",
  "email" => "jane.doe@example.com"
}
{:ok, new_person} = Humaans.People.create(client, person_params)

Telemetry

This library emits :telemetry events for all API requests. See Humaans.Telemetry for the full list of events, measurements, and metadata.

Pagination

Use Humaans.Pagination to iterate through large result sets without loading everything into memory:

# Stream all people 50 at a time
client
|> Humaans.Pagination.stream(&Humaans.People.list/2, page_size: 50)
|> Enum.each(fn person -> IO.puts(person.first_name) end)

# Fetch a specific page
{:ok, result} = Humaans.Pagination.page(client, &Humaans.People.list/2, 2, page_size: 25)

Summary

Types

t()

Functions

audit_events()

Access the Audit Events API.

bank_accounts()

Access the Bank Accounts API.

companies()

Access the Companies API.

compensation_types()

Access the Compensation Types API.

compensations()

Access the Compensations API.

custom_fields()

Access the Custom Fields API.

custom_values()

Access the Custom Values API.

document_folders()

Access the Document Folders API.

document_types()

Access the Document Types API.

documents()

Access the Documents API.

emergency_contacts()

Access the Emergency Contacts API.

equipment()

Access the Equipment API.

equipment_names()

Access the Equipment Names API.

equipment_types()

Access the Equipment Types API.

esign_bulk_recipients()

Access the Esign Bulk Recipients API.

esign_bulk_tokens()

Access the Esign Bulk Tokens API.

esign_bulks()

Access the Esign Bulks API.

esign_instances()

Access the Esign Instances API.

esign_templates()

Access the Esign Templates API.

identity_document_types()

Access the Identity Document Types API.

identity_documents()

Access the Identity Documents API.

job_roles()

Access the Job Roles API.

locations()

Access the Locations API.

me()

Access the current user's profile.

new(opts)

Creates a new client with the given access token and optional parameters.

okrs()

Access the OKRs API.

pagination()

Access pagination helpers.

people()

Access the People API.

performance_cycle_peer_nominations()

Access the Performance Cycle Peer Nominations API.

performance_cycles()

Access the Performance Cycles API.

performance_instances()

Access the Performance Instances API.

performance_ratings()

Access the Performance Ratings API.

performance_reviews()

Access the Performance Reviews API.

performance_summaries()

Access the Performance Summaries API.

performance_templates()

Access the Performance Templates API.

public_holiday_calendar_days()

Access the Public Holiday Calendar Days API.

public_holiday_calendars()

Access the Public Holiday Calendars API.

public_holidays()

Access the Public Holidays API.

query()

Access the query builder.

request_activity_logs()

Access the Request Activity Logs API.

request_comments()

Access the Request Comments API.

request_reviews()

Access the Request Reviews API.

request_types()

Access the Request Types API.

requests()

Access the Requests API.

role_members()

Access the Role Members API.

role_permissions()

Access the Role Permissions API.

roles()

Access the Roles API.

spaces()

Access the Spaces API.

tasks()

Access the Tasks API.

time_away()

Access the Time Away API.

time_away_adjustments()

Access the Time Away Adjustments API.

time_away_allocations()

Access the Time Away Allocations API.

time_away_policies()

Access the Time Away Policies API.

time_away_types()

Access the Time Away Types API.

timesheet_entries()

Access the Timesheet Entries API.

timesheet_submissions()

Access the Timesheet Submissions API.

token_info()

Access the current access token's metadata.

webhook_events()

Access the Webhook Events API.

webhooks()

Access the Webhooks API.

workflow_dependencies()

Access the Workflow Dependencies API.

workflow_form_responses()

Access the Workflow Form Responses API.

workflow_publications()

Access the Workflow Publications API.

workflow_slack_actions()

Access the Workflow Slack Actions API.

workflow_stats()

Access the Workflow Stats API.

working_pattern_allocations()

Access the Working Pattern Allocations API.

working_patterns()

Access the Working Patterns API.

Types

t()

@type t() :: %Humaans{
  access_token: String.t(),
  base_url: String.t(),
  http_client: module(),
  req_options: keyword()
}

Functions

audit_events()

Access the Audit Events API.

Returns the module that contains functions for working with audit event resources.

bank_accounts()

Access the Bank Accounts API.

Returns the module that contains functions for working with bank account resources.

companies()

Access the Companies API.

Returns the module that contains functions for working with company resources.

compensation_types()

Access the Compensation Types API.

Returns the module that contains functions for working with compensation type resources.

compensations()

Access the Compensations API.

Returns the module that contains functions for working with compensation resources.

custom_fields()

Access the Custom Fields API.

Returns the module that contains functions for working with custom field resources.

custom_values()

Access the Custom Values API.

Returns the module that contains functions for working with custom value resources.

document_folders()

Access the Document Folders API.

Returns the module that contains functions for working with document folder resources.

document_types()

Access the Document Types API.

Returns the module that contains functions for working with document type resources.

documents()

Access the Documents API.

Returns the module that contains functions for working with document resources.

emergency_contacts()

Access the Emergency Contacts API.

Returns the module that contains functions for working with emergency contact resources.

equipment()

Access the Equipment API.

Returns the module that contains functions for working with equipment resources.

equipment_names()

Access the Equipment Names API.

Returns the module that contains functions for working with equipment name resources.

equipment_types()

Access the Equipment Types API.

Returns the module that contains functions for working with equipment type resources.

esign_bulk_recipients()

Access the Esign Bulk Recipients API.

Returns the module that contains functions for working with esign bulk recipient resources.

esign_bulk_tokens()

Access the Esign Bulk Tokens API.

Returns the module that contains functions for working with esign bulk token resources.

esign_bulks()

Access the Esign Bulks API.

Returns the module that contains functions for working with esign bulk resources.

esign_instances()

Access the Esign Instances API.

Returns the module that contains functions for working with esign instance resources.

esign_templates()

Access the Esign Templates API.

Returns the module that contains functions for working with esign template resources.

identity_document_types()

Access the Identity Document Types API.

Returns the module that contains functions for working with identity document type resources.

identity_documents()

Access the Identity Documents API.

Returns the module that contains functions for working with identity document resources.

job_roles()

Access the Job Roles API.

Returns the module that contains functions for working with job role resources.

locations()

Access the Locations API.

Returns the module that contains functions for working with location resources.

me()

Access the current user's profile.

Returns Humaans.Me, which exposes get/1 for retrieving the authenticated user's profile.

new(opts)

@spec new(opts :: keyword()) :: map()

Creates a new client with the given access token and optional parameters.

Options

  • :access_token - The access token to use for authentication (required)
  • :base_url - The base URL for API requests (defaults to https://app.humaans.io/api)
  • :http_client - HTTP client module (defaults to Humaans.HTTPClient.Req)
  • :req_options - Keyword list merged into the default Req client config. Ignored when :http_client is overridden.

Examples

iex> client = Humaans.new(access_token: "some-access-token")
iex> is_map(client)
true

okrs()

Access the OKRs API.

Returns the module that contains functions for working with OKR resources.

pagination()

Access pagination helpers.

Returns Humaans.Pagination, which provides page/4 for fetching a specific page and stream/3 for lazily iterating all results.

people()

Access the People API.

Returns the module that contains functions for working with people resources.

performance_cycle_peer_nominations()

Access the Performance Cycle Peer Nominations API.

Returns the module that contains functions for working with peer nomination resources.

performance_cycles()

Access the Performance Cycles API.

Returns the module that contains functions for working with performance cycle resources.

performance_instances()

Access the Performance Instances API.

Returns the module that contains functions for working with performance instance resources.

performance_ratings()

Access the Performance Ratings API.

Returns the module that contains functions for working with performance rating resources.

performance_reviews()

Access the Performance Reviews API.

Returns the module that contains functions for working with performance review resources.

performance_summaries()

Access the Performance Summaries API.

Returns the module that contains functions for working with performance summary resources.

performance_templates()

Access the Performance Templates API.

Returns the module that contains functions for working with performance template resources.

public_holiday_calendar_days()

Access the Public Holiday Calendar Days API.

Returns the module that contains functions for working with public holiday calendar day resources.

public_holiday_calendars()

Access the Public Holiday Calendars API.

Returns the module that contains functions for working with public holiday calendar resources.

public_holidays()

Access the Public Holidays API.

Returns the module that contains functions for working with public holiday resources.

query()

Access the query builder.

Returns Humaans.Query, which provides eq/3, in_/3, nin/3, gt/3, gte/3, lt/3, lte/3, merge/2, and to_params/1 for building filter queries.

request_activity_logs()

Access the Request Activity Logs API.

Returns the module that contains functions for working with request activity log resources.

request_comments()

Access the Request Comments API.

Returns the module that contains functions for working with request comment resources.

request_reviews()

Access the Request Reviews API.

Returns the module that contains functions for working with request review resources.

request_types()

Access the Request Types API.

Returns the module that contains functions for working with request type resources.

requests()

Access the Requests API.

Returns the module that contains functions for working with request resources.

role_members()

Access the Role Members API.

Returns the module that contains functions for working with role member resources.

role_permissions()

Access the Role Permissions API.

Returns the module that contains functions for working with role permission resources.

roles()

Access the Roles API.

Returns the module that contains functions for working with role resources.

spaces()

Access the Spaces API.

Returns the module that contains functions for working with space (team/department) resources.

tasks()

Access the Tasks API.

Returns the module that contains functions for working with task resources.

time_away()

Access the Time Away API.

Returns the module that contains functions for working with time away resources.

time_away_adjustments()

Access the Time Away Adjustments API.

Returns the module that contains functions for working with time away adjustment resources.

time_away_allocations()

Access the Time Away Allocations API.

Returns the module that contains functions for working with time away allocation resources.

time_away_policies()

Access the Time Away Policies API.

Returns the module that contains functions for working with time away policy resources.

time_away_types()

Access the Time Away Types API.

Returns the module that contains functions for working with time away type resources.

timesheet_entries()

Access the Timesheet Entries API.

Returns the module that contains functions for working with timesheet entry resources.

timesheet_submissions()

Access the Timesheet Submissions API.

Returns the module that contains functions for working with timesheet submission resources.

token_info()

Access the current access token's metadata.

Returns Humaans.TokenInfo, which exposes get/1 for retrieving metadata (scopes, personId, etc.) about the current access token.

webhook_events()

Access the Webhook Events API.

Returns the module that contains functions for working with webhook event resources.

webhooks()

Access the Webhooks API.

Returns the module that contains functions for working with webhook resources.

workflow_dependencies()

Access the Workflow Dependencies API.

Returns the module that contains functions for working with workflow dependency resources.

workflow_form_responses()

Access the Workflow Form Responses API.

Returns the module that contains functions for working with workflow form response resources.

workflow_publications()

Access the Workflow Publications API.

Returns the module that contains functions for working with workflow publication resources.

workflow_slack_actions()

Access the Workflow Slack Actions API.

Returns the module that contains functions for working with workflow Slack action resources.

workflow_stats()

Access the Workflow Stats API.

Returns the module that contains functions for working with workflow stat resources.

working_pattern_allocations()

Access the Working Pattern Allocations API.

Returns the module that contains functions for working with working pattern allocation resources.

working_patterns()

Access the Working Patterns API.

Returns the module that contains functions for working with working pattern resources.