Custom Fields

Usage

List custom fields and their options:

import asyncio
import factorialhr

async def main():
    auth = factorialhr.AccessTokenAuth("your_access_token")
    async with factorialhr.ApiClient(auth=auth) as api:
        fields = factorialhr.FieldsEndpoint(api)
        response = await fields.all()
        for field in response.data():
            print(field.name, field.resource_type)

asyncio.run(main())

class factorialhr.CustomFieldsValuesEndpoint(api: ApiClient)[source]

Endpoint for custom fields values.

async all(**kwargs) → ListApiResponse[CustomFieldValue][source]

Get all custom field values.

Official documentation: custom_fields/values

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[CustomFieldValue]

async create(data: Mapping[str, Any], **kwargs) → CustomFieldValue[source]

Create a new custom field value.

Official documentation: custom_fields/values

Parameters:

data (Mapping[str, Any]) – Payload for the new record (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

CustomFieldValue

async get(**kwargs) → MetaApiResponse[CustomFieldValue][source]

Get custom field values with pagination metadata.

Official documentation: custom_fields/values

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[CustomFieldValue]

async get_by_id(value_id: int | str, **kwargs) → CustomFieldValue[source]

Get a specific custom field value by ID.

Official documentation: custom_fields/values

Parameters:

value_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

CustomFieldValue

async update(value_id: int | str, data: Mapping[str, Any], **kwargs) → CustomFieldValue[source]

Update a custom field value.

Official documentation: custom_fields/values

Parameters:

value_id (int | str) – The unique identifier of the record to update.
data (Mapping[str, Any]) – Payload with fields to update (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The updated record.

Return type:

CustomFieldValue

class factorialhr.CustomFieldValue(*, id: int, value: bool | None = None, long_text_value: str | None = None, custom_field_identifier: str, date_value: date | None = None, single_choice_value: str | None = None, cents_value: int | None = None, valuable_id: int, field_id: int, valuable_type: str, label: str | None = None, required: bool | None = None, usage_group_id: int | None = None, usage_group_slug: str | None = None, updated_at: datetime | None = None)[source]

Model for custom_fields_value.

cents_value: int | None: Custom field number value

custom_field_identifier: str: Custom field identifier

date_value: date | None: Custom field date value

field_id: int: Field identifier

id: int: Unique identifier for the custom field value

label: str | None: Field label

long_text_value: str | None: Custom field text value

required: bool | None: Whether field is required

single_choice_value: str | None: Custom field single choice value

updated_at: datetime | None: The date and time the custom field value was last updated

usage_group_id: int | None: Usage group identifier

usage_group_slug: str | None: Usage group slug

valuable_id: int: Valuable identifier

valuable_type: str: Valuable type

value: bool | None: Custom Fields value

Model for custom_fields_field.

field_type: FieldType: The type of the field’s value

id: int: Field identifier

label_text: str: Field label

legal_entity_id: int | None: Legal entity id where this field belongs

legal_entity_name: str | None: Legal entity name where this field belongs

max_value: int | None: Maximum value in range field type

min_value: int | None: Minimum value in range field type

position: int | None: Field position within employee profile

required: bool | None: Requirement to fill this field

slug: str | None: Custom field slug

class factorialhr.FieldsEndpoint(api: ApiClient)[source]

Endpoint for custom fields fields.

async all(**kwargs) → ListApiResponse[Field][source]

Get all custom fields.

Official documentation: custom_fields/fields

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[Field]

async create(data: Mapping[str, Any], **kwargs) → Field[source]

Create a new custom field.

Official documentation: custom_fields/fields

Parameters:

data (Mapping[str, Any]) – Payload for the new record (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

Field

async delete(field_id: int | str, **kwargs) → None[source]

Delete a custom field.

Official documentation: custom_fields/fields

Parameters:

field_id (int | str) – The unique identifier of the record to delete.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

None.

Return type:

None

async get(**kwargs) → MetaApiResponse[Field][source]

Get custom fields with pagination metadata.

Official documentation: custom_fields/fields

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[Field]

async get_by_id(field_id: int | str, **kwargs) → Field[source]

Get a specific custom field by ID.

Official documentation: custom_fields/fields

Parameters:

field_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

Field

class factorialhr.Option(*, id: int, label: str | None = None, value: str | None = None, is_active: bool | None = None, field_id: int | None = None)[source]

Model for custom_fields_option.

field_id: int | None: Custom Fields identifier

id: int: Option identifier

is_active: bool | None: Flag to make the option available

label: str | None: Title for option

value: str | None: Option value

class factorialhr.OptionsEndpoint(api: ApiClient)[source]

Endpoint for custom fields options.

async all(**kwargs) → ListApiResponse[Option][source]

Get all custom field options.

Official documentation: custom_fields/options

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[Option]

async create(data: Mapping[str, Any], **kwargs) → Option[source]

Create a new custom field option.

Official documentation: custom_fields/options

Parameters:

data (Mapping[str, Any]) – Payload for the new record (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

Option

async get(**kwargs) → MetaApiResponse[Option][source]

Get custom field options with pagination metadata.

Official documentation: custom_fields/options

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[Option]

async get_by_id(option_id: int | str, **kwargs) → Option[source]

Get a specific custom field option by ID.

Official documentation: custom_fields/options

Parameters:

option_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

Option

class factorialhr.ResourceField(*, id: int, field_id: int | None = None)[source]

Model for custom_fields_resource_field.

field_id: int | None: Custom Field identifier

id: int: Resource field identifier

class factorialhr.ResourceFieldsEndpoint(api: ApiClient)[source]

Endpoint for custom fields resource fields.

async all(**kwargs) → ListApiResponse[ResourceField][source]

Get all custom resource fields.

Official documentation: custom_fields/resource_fields

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing the list of records.
Return type:: ListApiResponse[ResourceField]

async create(data: Mapping[str, Any], **kwargs) → ResourceField[source]

Create a new custom resource field.

Official documentation: custom_fields/resource_fields

Parameters:

data (Mapping[str, Any]) – Payload for the new record (key-value mapping).
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The created record.

Return type:

ResourceField

async get(**kwargs) → MetaApiResponse[ResourceField][source]

Get custom resource fields with pagination metadata.

Official documentation: custom_fields/resource_fields

Parameters:: kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.
Raises:: httpx.HTTPStatusError – When the API returns an error status code.
Returns:: Response containing records and pagination metadata.
Return type:: MetaApiResponse[ResourceField]

async get_by_id(resource_field_id: int | str, **kwargs) → ResourceField[source]

Get a specific custom resource field by ID.

Official documentation: custom_fields/resource_fields

Parameters:

resource_field_id (int | str) – The unique identifier.
kwargs (optional) – Optional keyword arguments (e.g. params for query string) forwarded to the HTTP request.

Raises:

httpx.HTTPStatusError – When the API returns an error status code.

Returns:

The record.

Return type:

ResourceField