Configuration¶

Reached as client.config, a container exposing five sub-namespaces over Alma's /conf endpoints.

client.config.code_tables is the one to reach for when another method wants a code you do not have to hand:

table = await client.config.code_tables.get_code_table("POLineCancellationReasons")
valid = [r.code for r in table.row if r.enabled == "true"]

`client.config`¶

AlmaClientConfigNS ¶

AlmaClientConfigNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for config/admin functionality, exposed at client.config.

A container only – it has no methods of its own. The work is done by its five sub-namespaces:

Attribute	Class
`client.config.sets`	`AlmaClientConfigSetsNS`
`client.config.libraries`	`AlmaClientConfigLibrariesNS`
`client.config.letters`	`AlmaClientConfigLettersNS`
`client.config.jobs`	`AlmaClientConfigJobsNS`
`client.config.code_tables`	`AlmaClientConfigCodeTablesNS`

`client.config.sets`¶

AlmaClientConfigSetsNS ¶

AlmaClientConfigSetsNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for set functionality, exposed at client.config.sets.

Alma sets come in two flavours: itemized sets hold an explicit list of member IDs, while logical sets are saved queries evaluated when the set is used. Only itemized sets can have their membership edited with manage_members.

get_list `async` Alma: Retrieve a list of Sets ¶

get_list(
    content_type: str | None = ...,
    set_type: Literal["ITEMIZED", "LOGICAL"] | None = ...,
    q: str | None = ...,
    limit: int = ...,
    offset: int = ...,
    set_origin: Literal["UI", "UI_CZ"] = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_list(
    content_type: str | None = ...,
    set_type: Literal["ITEMIZED", "LOGICAL"] | None = ...,
    q: str | None = ...,
    limit: int = ...,
    offset: int = ...,
    set_origin: Literal["UI", "UI_CZ"] = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

List the sets defined in the institution.

Parameters:

Name	Type	Description	Default
`content_type`	`str \| None`	Restrict to sets over one kind of record, e.g. `"BIB_MMS"`, `"ITEM"`, `"USER"`. Values come from the `SetContentType` code table.	`None`
`set_type`	`Literal['ITEMIZED', 'LOGICAL'] \| None`	`"ITEMIZED"` for explicit member lists, `"LOGICAL"` for saved queries. Both are returned when omitted.	`None`
`q`	`str \| None`	Search query, in Alma's `field~value` form, e.g. `"name~Annual"`.	`None`
`limit`	`int`	Maximum number of sets to return in this page.	`10`
`offset`	`int`	Index of the first set to return, for paging.	`0`
`set_origin`	`Literal['UI', 'UI_CZ']`	`"UI"` for sets created in this institution zone, `"UI_CZ"` for sets originating in the community zone.	`'UI'`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A page of sets, with `total_record_count` giving the full size of the
`Any`	result so the caller can page through it.

Raises:

Type	Description
`APIClientError`	If the query or content type is not valid.

Examples:

page = await client.config.sets.get_list(
    set_type="ITEMIZED", content_type="BIB_MMS", limit=100
)
print(page.total_record_count)
for s in page.set:
    print(s.id, s.name)

get_set `async` Alma: Retrieve a Set ¶

get_set(set_id: str, *, model: type[_ModelT]) -> _ModelT

get_set(set_id: str, *, model: None = ...) -> RESP_TYPE

Retrieve a single set by its ID.

Returns the set's metadata – name, type, content type, member count – but not its members. Use get_members for those.

Parameters:

Name	Type	Description	Default
`set_id`	`str`	The numeric set identifier.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The set record.

Raises:

Type	Description
`APIClientError`	If no set with that ID exists.

Examples:

s = await client.config.sets.get_set("1234567890")
print(s.name, s.number_of_members.value)

create `async` Alma: Create a Set ¶

create(
    data: Body,
    population: str | None = ...,
    job_instance_id: str | None = ...,
    from_logical_set: str | None = ...,
    combine: str | None = ...,
    set1: str | None = ...,
    set2: str | None = ...,
    nz_set_from_iz_set: str | None = ...,
    indication_rule: str | None = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

create(
    data: Body,
    population: str | None = ...,
    job_instance_id: str | None = ...,
    from_logical_set: str | None = ...,
    combine: str | None = ...,
    set1: str | None = ...,
    set2: str | None = ...,
    nz_set_from_iz_set: str | None = ...,
    indication_rule: str | None = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

Create a set.

Alma builds the new set in one of several ways depending on which optional argument is supplied – from a job's results, by combining two existing sets, by copying a logical set, and so on. Supply at most one of them; the plain form with none creates an empty itemized set from data alone.

Parameters:

Name	Type	Description	Default
`data`	`Body`	The set record to create – at minimum `name`, `type` and `content` must be present. Accepts a mapping or any object implementing `dump`/`model_dump`.	required
`population`	`str \| None`	Which subset of a job's output to build the set from, e.g. `"MULTI_MATCHES"`. Requires `job_instance_id`.	`None`
`job_instance_id`	`str \| None`	Build the set from the results of this job instance.	`None`
`from_logical_set`	`str \| None`	ID of a logical set to itemize into the new set.	`None`
`combine`	`str \| None`	Set operation to apply to `set1` and `set2` – one of `"AND"`, `"OR"`, `"NOT"`.	`None`
`set1`	`str \| None`	ID of the first operand set for `combine`.	`None`
`set2`	`str \| None`	ID of the second operand set for `combine`.	`None`
`nz_set_from_iz_set`	`str \| None`	ID of an institution-zone set to build the corresponding network-zone set from.	`None`
`indication_rule`	`str \| None`	ID of an indication rule to filter members by.	`None`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The newly created set record, including its assigned `id`.

Raises:

Type	Description
`APIClientError`	If the body is incomplete, the referenced sets or job instance do not exist, or the combination of arguments is not valid.

Examples:

new_set = await client.config.sets.create(
    {
        "name": "Weeding candidates 2026",
        "type": {"value": "ITEMIZED"},
        "content": {"value": "ITEM"},
        "private": {"value": "false"},
    }
)

get_members `async` Alma: Retrieve Set Members ¶

get_members(
    set_id: str,
    limit: int = ...,
    offset: int = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_members(
    set_id: str,
    limit: int = ...,
    offset: int = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

Retrieve a page of a set's members.

Parameters:

Name	Type	Description	Default
`set_id`	`str`	The numeric set identifier.	required
`limit`	`int`	Maximum number of members to return in this page.	`100`
`offset`	`int`	Index of the first member to return, for paging.	`0`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A page of members, with `total_record_count` giving the size of the
`Any`	whole set.

Raises:

Type	Description
`APIClientError`	If no set with that ID exists.

Examples:

Page through a set of any size:

offset, members = 0, []
while True:
    page = await client.config.sets.get_members("1234567890", offset=offset)
    members.extend(page.member)
    offset += 100
    if offset >= int(page.total_record_count):
        break

delete_set `async` Alma: Delete a Set ¶

delete_set(set_id: str) -> None

Delete a set.

Deletes the set itself, not the records it contains.

Parameters:

Name	Type	Description	Default
`set_id`	`str`	The numeric set identifier.	required

Returns:

Type	Description
`None`	`None`. Alma returns an empty body on success.

Raises:

Type	Description
`APIClientError`	If no set with that ID exists, or it is in use by a scheduled job.

Examples:

await client.config.sets.delete_set("1234567890")

manage_members `async` Alma: Manage Members ¶

manage_members(
    set_id: str,
    member_id_list: list[str],
    *,
    id_type: str | None = ...,
    op: Literal[
        "add_members", "delete_members", "replace_members"
    ],
    fail_on_invalid: bool = ...,
    model: type[_ModelT],
) -> _ModelT

manage_members(
    set_id: str,
    member_id_list: list[str],
    *,
    id_type: str | None = ...,
    op: Literal[
        "add_members", "delete_members", "replace_members"
    ],
    fail_on_invalid: bool = ...,
    model: None = ...,
) -> RESP_TYPE

Add, remove or replace the members of an itemized set.

Alma requires the whole set record on this call, so this method fetches the set first and then posts it back with the member list attached – it costs two API requests, not one. Only itemized sets can be edited this way; logical sets derive their membership from a query.

Parameters:

Name	Type	Description	Default
`set_id`	`str`	The numeric set identifier.	required
`member_id_list`	`list[str]`	The record identifiers to act on. These must match the set's content type – MMS IDs for a `BIB_MMS` set, item PIDs for an `ITEM` set, and so on.	required
`id_type`	`str \| None`	The kind of identifier in `member_id_list` when it is not the set's default, e.g. `"BARCODE"` for an item set.	`None`
`op`	`Literal['add_members', 'delete_members', 'replace_members']`	`"add_members"` appends, `"delete_members"` removes, and `"replace_members"` discards the existing membership entirely.	required
`fail_on_invalid`	`bool`	When True, an unrecognised identifier fails the whole call. Set to False to have Alma skip bad IDs and apply the rest.	`True`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The updated set record.

Raises:

Type	Description
`APIClientError`	If the set does not exist, is a logical set, or an identifier is invalid and `fail_on_invalid` is True.

Examples:

await client.config.sets.manage_members(
    "1234567890",
    ["99123456789012345", "99123456789012346"],
    op="add_members",
    fail_on_invalid=False,
)

`client.config.libraries`¶

AlmaClientConfigLibrariesNS ¶

AlmaClientConfigLibrariesNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for library functionality, exposed at client.config.libraries.

Reads the institution's physical structure: its libraries, the locations and circulation desks within each, and its work departments. Everything here is read-only – Alma does not expose library configuration for editing over the API.

get_libraries `async` Alma: Retrieve Libraries ¶

get_libraries(*, model: type[_ModelT]) -> _ModelT

get_libraries(*, model: None = ...) -> RESP_TYPE

List every library in the institution.

Unpaginated – Alma returns them all in one response.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	All libraries, each with its `code`, `name` and `path`. The codes
`Any`	are what the other methods on this namespace expect.

Examples:

libs = await client.config.libraries.get_libraries()
for lib in libs.library:
    print(lib.code, lib.name)

get_circ_desks `async` Alma: Retrieve Circulation Desks ¶

get_circ_desks(
    library: str, *, model: type[_ModelT]
) -> _ModelT

get_circ_desks(
    library: str, *, model: None = ...
) -> RESP_TYPE

List the circulation desks belonging to a library.

Circulation desk codes are needed when creating loans and scanning items in.

Parameters:

Name	Type	Description	Default
`library`	`str`	The library code, as returned by `get_libraries`.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The library's circulation desks.

Raises:

Type	Description
`APIClientError`	If no library with that code exists.

Examples:

desks = await client.config.libraries.get_circ_desks("MAIN")
for desk in desks.circ_desk:
    print(desk.code, desk.name)

get_locations `async` Alma: Retrieve Locations ¶

get_locations(
    library: str, *, model: type[_ModelT]
) -> _ModelT

get_locations(
    library: str, *, model: None = ...
) -> RESP_TYPE

List the shelving locations within a library.

Parameters:

Name	Type	Description	Default
`library`	`str`	The library code, as returned by `get_libraries`.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The library's locations, each with its `code` and `name`.

Raises:

Type	Description
`APIClientError`	If no library with that code exists.

Examples:

locs = await client.config.libraries.get_locations("MAIN")
for loc in locs.location:
    print(loc.code, loc.name)

get_location `async` Alma: Retrieve Location ¶

get_location(
    library: str, location: str, *, model: type[_ModelT]
) -> _ModelT

get_location(
    library: str, location: str, *, model: None = ...
) -> RESP_TYPE

Retrieve a single shelving location.

Parameters:

Name	Type	Description	Default
`library`	`str`	The library code the location belongs to.	required
`location`	`str`	The location code.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The location record, including its external name and fulfilment unit.

Raises:

Type	Description
`APIClientError`	If the library or location code does not exist.

Examples:

loc = await client.config.libraries.get_location("MAIN", "STACKS")
print(loc.external_name)

get_departments `async` Alma: Retrieve Departments ¶

get_departments(
    department_type: Literal["DIGI", "ALL"] = "ALL",
    view: Literal["brief", "FULL"] = "brief",
    library: str | None = None,
    *,
    model: type[_ModelT],
) -> _ModelT

get_departments(
    department_type: Literal["DIGI", "ALL"] = "ALL",
    view: Literal["brief", "FULL"] = "brief",
    library: str | None = None,
    *,
    model: None = ...,
) -> RESP_TYPE

List the institution's work departments.

Departments are the work areas material passes through – acquisitions, digitisation, binding – and their codes are what receive_existing_item and the request-processing endpoints expect.

Parameters:

Name	Type	Description	Default
`department_type`	`Literal['DIGI', 'ALL']`	`"ALL"` for every department, or `"DIGI"` to restrict to digitisation departments.	`'ALL'`
`view`	`Literal['brief', 'FULL']`	`"brief"` returns codes and names only; `"FULL"` adds each department's owners, work stations and served libraries.	`'brief'`
`library`	`str \| None`	Restrict to departments serving this library code.	`None`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The matching departments.

Raises:

Type	Description
`APIClientError`	If the library code does not exist.

Examples:

depts = await client.config.libraries.get_departments(
    department_type="DIGI", view="FULL", library="MAIN"
)

`client.config.letters`¶

AlmaClientConfigLettersNS ¶

AlmaClientConfigLettersNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for letter functionality, exposed at client.config.letters.

Letters are the XSL templates Alma renders notifications from – overdue notices, hold shelf slips, and so on. Note that update_letter takes and returns XML rather than a mapping, since the template body is itself XSL.

get_letters `async` Alma: Retrieve Letters ¶

get_letters(*, model: type[_ModelT]) -> _ModelT

get_letters(*, model: None = ...) -> RESP_TYPE

List the institution's letter templates.

Returns letters only. Use get_components for the shared header and footer fragments.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	All letter templates, each with its `code`, `description` and
`Any`	enabled state.

Examples:

letters = await client.config.letters.get_letters()
for letter in letters.letter:
    print(letter.code, letter.enabled)

get_components `async` Alma: Retrieve Letters ¶

get_components(*, model: type[_ModelT]) -> _ModelT

get_components(*, model: None = ...) -> RESP_TYPE

List the shared letter components.

Components are the fragments – headers, footers, style blocks – that individual letters include. Same endpoint as get_letters, filtered to type=COMPONENT.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	All letter components.

Examples:

components = await client.config.letters.get_components()

get_letter `async` Alma: Retrieve Letter ¶

get_letter(
    letter_id: str, *, model: type[_ModelT]
) -> _ModelT

get_letter(
    letter_id: str, *, model: None = ...
) -> RESP_TYPE

Retrieve a single letter template, including its XSL body.

Parameters:

Name	Type	Description	Default
`letter_id`	`str`	The letter code, e.g. `"FulOverdueNotice"`.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The letter record, with the template source in its `translations`.

Raises:

Type	Description
`APIClientError`	If no letter with that code exists.

Examples:

letter = await client.config.letters.get_letter("FulOverdueNotice")

update_letter `async` Alma: Update Letter ¶

update_letter(
    letter_id: str, data: str, *, model: type[_ModelT]
) -> _ModelT

update_letter(
    letter_id: str, data: str, *, model: None = ...
) -> RESP_TYPE

Replace a letter template.

Unlike the rest of almapy this method sends XML: data is a string, posted with Content-Type: application/xml, not a mapping. Fetch the current letter with get_letter first – Alma replaces the whole record, so a partial body drops the rest of it.

Parameters:

Name	Type	Description	Default
`letter_id`	`str`	The letter code, e.g. `"FulOverdueNotice"`.	required
`data`	`str`	The complete letter record as an XML string.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The updated letter record.

Raises:

Type	Description
`APIClientError`	If no letter with that code exists, or the XML is malformed or fails Alma's schema validation.

Examples:

xml = "<letter><code>FulOverdueNotice</code>...</letter>"
await client.config.letters.update_letter("FulOverdueNotice", xml)

`client.config.jobs`¶

AlmaClientConfigJobsNS ¶

AlmaClientConfigJobsNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for job functionality, exposed at client.config.jobs.

Covers two related areas of Alma configuration:

Jobs – the definitions Alma can run, the instances (individual runs) of each, and the records a run matched. Submitting a job is asynchronous: submit_job returns immediately with an instance link, and progress is read back with get_job_instance.
Integration profiles – the configuration for Alma's external system integrations, which are the only objects here that can be created and edited.

get_jobs `async` Alma: Retrieve Jobs ¶

get_jobs(
    limit: int = ...,
    offset: int = ...,
    *,
    category: str | None = ...,
    job_type: Literal["MANUAL", "SCHEDULED", "OTHER"]
    | None = ...,
    profile_id: str | None = ...,
    model: type[_ModelT],
) -> _ModelT

get_jobs(
    limit: int = ...,
    offset: int = ...,
    *,
    category: str | None = ...,
    job_type: Literal["MANUAL", "SCHEDULED", "OTHER"]
    | None = ...,
    profile_id: str | None = ...,
    model: None = ...,
) -> RESP_TYPE

List the jobs defined in the institution.

Parameters:

Name	Type	Description	Default
`limit`	`int`	Maximum number of jobs to return in this page.	`10`
`offset`	`int`	Index of the first job to return, for paging.	`0`
`category`	`str \| None`	Restrict to one job category, e.g. `"IMPORT"`, `"EXPORT"`, `"REPOSITORY"`.	`None`
`job_type`	`Literal['MANUAL', 'SCHEDULED', 'OTHER'] \| None`	`"MANUAL"` for jobs run against a set on demand, `"SCHEDULED"` for jobs Alma runs on a timetable, `"OTHER"` for the rest.	`None`
`profile_id`	`str \| None`	Restrict to jobs belonging to this integration or import profile.	`None`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A page of jobs, with `total_record_count` giving the full result size.

Raises:

Type	Description
`APIClientError`	If the category or profile ID is not valid.

Examples:

jobs = await client.config.jobs.get_jobs(job_type="MANUAL", limit=100)
for job in jobs.job:
    print(job.id, job.name)

get_job `async` Alma: Retrieve Job Details ¶

get_job(job_id: str, *, model: type[_ModelT]) -> _ModelT

get_job(job_id: str, *, model: None = ...) -> RESP_TYPE

Retrieve a single job definition.

The response lists the job's parameters, which is how you discover what submit_job expects in its body for this particular job.

Parameters:

Name	Type	Description	Default
`job_id`	`str`	The job identifier, e.g. `"M1"` or a numeric ID.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The job definition, including its parameter list.

Raises:

Type	Description
`APIClientError`	If no job with that ID exists.

Examples:

job = await client.config.jobs.get_job("M1")
for param in job.parameter:
    print(param.name.value, param.type.value)

submit_job `async` Alma: Submit a manual or scheduled job ¶

submit_job(
    job_id: str, job: Body, *, model: type[_ModelT]
) -> _ModelT

submit_job(
    job_id: str, job: Body, *, model: None = ...
) -> RESP_TYPE

Submit a job for execution.

This is asynchronous: Alma queues the job and returns immediately with a link to the new instance. Poll get_job_instance to follow its progress.

Being a POST, this call is not replayed if the response is lost in transit – a retry could queue the job twice. See the retry semantics in Rate limiting.

Parameters:

Name	Type	Description	Default
`job_id`	`str`	The job identifier to run.	required
`job`	`Body`	The job's parameters, normally a `parameter` list of `{"name": {"value": ...}, "value": ...}` entries. The shape depends entirely on the job; read it off `get_job` for the job in question. Manual jobs normally take at least a set ID. Accepts a mapping or any object implementing `dump`/`model_dump`.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A record containing `additional_info`, whose `link` identifies the
`Any`	newly created job instance.

Raises:

Type	Description
`APIClientError`	If the job does not exist, a required parameter is missing, or the job cannot be run manually.

Examples:

submitted = await client.config.jobs.submit_job(
    "M1",
    {"parameter": [{"name": {"value": "set_id"}, "value": "1234567890"}]},
)
instance_id = submitted.additional_info.link.rsplit("/", 1)[-1]

get_job_instances `async` Alma: Retrieve Job Instances ¶

get_job_instances(
    job_id: str,
    limit: int = ...,
    offset: int = ...,
    submit_date_from: str | None = ...,
    submit_date_to: str | None = ...,
    status: str | None = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_job_instances(
    job_id: str,
    limit: int = ...,
    offset: int = ...,
    submit_date_from: str | None = ...,
    submit_date_to: str | None = ...,
    status: str | None = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

List the runs (instances) of a job.

Parameters:

Name	Type	Description	Default
`job_id`	`str`	The job identifier.	required
`limit`	`int`	Maximum number of instances to return in this page.	`10`
`offset`	`int`	Index of the first instance to return, for paging.	`0`
`submit_date_from`	`str \| None`	Earliest submission date to include, as `YYYY-MM-DD`.	`None`
`submit_date_to`	`str \| None`	Latest submission date to include, as `YYYY-MM-DD`.	`None`
`status`	`str \| None`	Restrict to one run status, e.g. `"COMPLETED_SUCCESS"`, `"COMPLETED_FAILED"`, `"RUNNING"`.	`None`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A page of job instances, most recent first.

Raises:

Type	Description
`APIClientError`	If the job does not exist or a date is malformed.

Examples:

runs = await client.config.jobs.get_job_instances(
    "M1", status="COMPLETED_FAILED", submit_date_from="2026-07-01"
)

get_job_instance `async` Alma: Retrieve Job Instance Details ¶

get_job_instance(
    job_id: str, instance_id: str, *, model: type[_ModelT]
) -> _ModelT

get_job_instance(
    job_id: str, instance_id: str, *, model: None = ...
) -> RESP_TYPE

Retrieve a single job run, including its status and counters.

This is what you poll after submit_job: the status field reports progress, and counter carries the per-stage record counts once the run finishes.

Parameters:

Name	Type	Description	Default
`job_id`	`str`	The job identifier.	required
`instance_id`	`str`	The identifier of the individual run.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The job instance record.

Raises:

Type	Description
`APIClientError`	If the job or instance does not exist.

Examples:

run = await client.config.jobs.get_job_instance("M1", "9876543210")
print(run.status.value, run.progress)

get_job_instance_matches `async` Alma: Retrieve Job Matching Details ¶

get_job_instance_matches(
    job_id: str,
    instance_id: str,
    single_or_multi: Literal["single", "multi"],
    limit: int = ...,
    offset: int = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_job_instance_matches(
    job_id: str,
    instance_id: str,
    single_or_multi: Literal["single", "multi"],
    limit: int = ...,
    offset: int = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

Retrieve the records a job run matched.

Applies to import and matching jobs, which classify each incoming record by how many existing records it matched.

Parameters:

Name	Type	Description	Default
`job_id`	`str`	The job identifier.	required
`instance_id`	`str`	The identifier of the individual run.	required
`single_or_multi`	`Literal['single', 'multi']`	`"single"` returns records that matched exactly one existing record, `"multi"` those that matched more than one and so need manual resolution.	required
`limit`	`int`	Maximum number of matches to return in this page.	`10`
`offset`	`int`	Index of the first match to return, for paging.	`0`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A page of matched records.

Raises:

Type	Description
`APIClientError`	If the job or instance does not exist, or the job is not one that produces match results.

Examples:

ambiguous = await client.config.jobs.get_job_instance_matches(
    "M1", "9876543210", "multi", limit=100
)

get_integration_profiles `async` Alma: Retrieve a list of Integration Profiles ¶

get_integration_profiles(
    profile_type: str | None = ...,
    query: str | None = ...,
    limit: int = ...,
    offset: int = ...,
    *,
    model: type[_ModelT],
) -> _ModelT

get_integration_profiles(
    profile_type: str | None = ...,
    query: str | None = ...,
    limit: int = ...,
    offset: int = ...,
    *,
    model: None = ...,
) -> RESP_TYPE

List the institution's integration profiles.

Parameters:

Name	Type	Description	Default
`profile_type`	`str \| None`	Restrict to one profile type, e.g. `"SSO"`, `"DISCOVERY"`, `"OAI"`.	`None`
`query`	`str \| None`	Search query, in Alma's `field~value` form.	`None`
`limit`	`int`	Maximum number of profiles to return in this page.	`10`
`offset`	`int`	Index of the first profile to return, for paging.	`0`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	A page of integration profiles.

Raises:

Type	Description
`APIClientError`	If the profile type or query is not valid.

Examples:

profiles = await client.config.jobs.get_integration_profiles(
    profile_type="SSO"
)

get_integration_profile `async` Alma: Retrieve an Integration Profile ¶

get_integration_profile(
    profile_id: str, *, model: type[_ModelT]
) -> _ModelT

get_integration_profile(
    profile_id: str, *, model: None = ...
) -> RESP_TYPE

Retrieve a single integration profile.

Parameters:

Name	Type	Description	Default
`profile_id`	`str`	The profile identifier.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The integration profile record, including its type-specific settings.

Raises:

Type	Description
`APIClientError`	If no profile with that ID exists.

Examples:

profile = await client.config.jobs.get_integration_profile("1234567890")

update_integration_profile `async` Alma: Update an Integration Profile ¶

update_integration_profile(
    profile_id: str, data: Body, *, model: type[_ModelT]
) -> _ModelT

update_integration_profile(
    profile_id: str, data: Body, *, model: None = ...
) -> RESP_TYPE

Replace an integration profile.

Alma replaces the whole profile, so fetch it with get_integration_profile and modify that rather than sending a partial body.

Parameters:

Name	Type	Description	Default
`profile_id`	`str`	The profile identifier.	required
`data`	`Body`	The full, modified profile record. Accepts a mapping or any object implementing `dump`/`model_dump`.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The updated integration profile record.

Raises:

Type	Description
`APIClientError`	If no profile with that ID exists, or the body fails Alma's validation for the profile type.

Examples:

profile = await client.config.jobs.get_integration_profile("1234567890")
profile.description = "Updated by nightly sync"
await client.config.jobs.update_integration_profile("1234567890", profile)

create_integration_profile `async` Alma: Retrieve an Integration Profile ¶

create_integration_profile(
    data: Body, *, model: type[_ModelT]
) -> _ModelT

create_integration_profile(
    data: Body, *, model: None = ...
) -> RESP_TYPE

Create an integration profile.

Being a POST, this call is not replayed if the response is lost in transit – a retry could create a second profile. See Rate limiting.

Parameters:

Name	Type	Description	Default
`data`	`Body`	The profile record to create. The required fields depend on the profile `type`. Accepts a mapping or any object implementing `dump`/`model_dump`.	required
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The newly created profile record, including its assigned ID.

Raises:

Type	Description
`APIClientError`	If the body is incomplete or fails Alma's validation for the profile type.

Examples:

profile = await client.config.jobs.create_integration_profile(
    {"name": "Nightly patron load", "type": {"value": "USER"}}
)

`client.config.code_tables`¶

AlmaClientConfigCodeTablesNS ¶

AlmaClientConfigCodeTablesNS(client: _AlmaExecutable)

Bases: BaseNamespace

Namespace for code table functionality, exposed at client.config.code_tables.

Worth reaching for when another method wants a code you do not have to hand: institutions add and disable rows freely, so the live table is the only dependable list.

get_code_tables `async` Alma: Retrieve Code Tables ¶

get_code_tables(*, model: type[_ModelT]) -> _ModelT

get_code_tables(*, model: None = ...) -> RESP_TYPE

List the names of every code table in the institution.

Returns table names only, not their rows – use get_code_table for the contents of one.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	All code table names.

Examples:

tables = await client.config.code_tables.get_code_tables()

get_code_table `async` Alma: Retrieve Code-table ¶

get_code_table(
    table_code: str,
    *,
    lang: str = ...,
    model: type[_ModelT],
) -> _ModelT

get_code_table(
    table_code: str, *, lang: str = ..., model: None = ...
) -> RESP_TYPE

Retrieve a code table and its rows.

Parameters:

Name	Type	Description	Default
`table_code`	`str`	The table name, e.g. `"POLineCancellationReasons"`, `"RequestTypes"`, `"UserBlockDescriptions"`.	required
`lang`	`str`	Two-letter language code for the row descriptions.	`'en'`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The code table, whose `row` list carries each `code`, its
`Any`	`description`, and whether it is `enabled`. Disabled rows are still
`Any`	returned, and Alma rejects them if used.

Raises:

Type	Description
`APIClientError`	If no table with that name exists.

Examples:

Discover the cancellation reasons this institution accepts:

table = await client.config.code_tables.get_code_table(
    "POLineCancellationReasons"
)
valid = [r.code for r in table.row if r.enabled == "true"]

update_code_table `async` Alma: Update Code-table ¶

update_code_table(
    table_code: str,
    data: Body,
    *,
    lang: str = ...,
    model: type[_ModelT],
) -> _ModelT

update_code_table(
    table_code: str,
    data: Body,
    *,
    lang: str = ...,
    model: None = ...,
) -> RESP_TYPE

Replace a code table's rows.

Alma replaces the entire table, so fetch it with get_code_table and modify that – sending only the rows you care about deletes every other row in the table.

Parameters:

Name	Type	Description	Default
`table_code`	`str`	The table name.	required
`data`	`Body`	The full, modified code table record. Accepts a mapping or any object implementing `dump`/`model_dump`.	required
`lang`	`str`	Two-letter language code the descriptions in `data` are written in. Must match the language the table was fetched in.	`'en'`
`model`	`Any`	Optional Pydantic model class to validate the response into.	`None`

Returns:

Type	Description
`Any`	The updated code table.

Raises:

Type	Description
`APIClientError`	If no table with that name exists, the table is not editable, or a row is malformed.

Examples:

table = await client.config.code_tables.get_code_table("MyLocalTable")
table.row.append({"code": "NEW", "description": "New reason", "enabled": "true"})
await client.config.code_tables.update_code_table("MyLocalTable", table)

Configuration¶

client.config¶

AlmaClientConfigNS ¶

client.config.sets¶

AlmaClientConfigSetsNS ¶

get_list async Alma: Retrieve a list of Sets ¶

get_set async Alma: Retrieve a Set ¶

create async Alma: Create a Set ¶

get_members async Alma: Retrieve Set Members ¶

delete_set async Alma: Delete a Set ¶

manage_members async Alma: Manage Members ¶

client.config.libraries¶

AlmaClientConfigLibrariesNS ¶

get_libraries async Alma: Retrieve Libraries ¶

get_circ_desks async Alma: Retrieve Circulation Desks ¶

get_locations async Alma: Retrieve Locations ¶

get_location async Alma: Retrieve Location ¶

get_departments async Alma: Retrieve Departments ¶

client.config.letters¶

AlmaClientConfigLettersNS ¶

get_letters async Alma: Retrieve Letters ¶

get_components async Alma: Retrieve Letters ¶

get_letter async Alma: Retrieve Letter ¶

update_letter async Alma: Update Letter ¶

client.config.jobs¶

AlmaClientConfigJobsNS ¶

get_jobs async Alma: Retrieve Jobs ¶

get_job async Alma: Retrieve Job Details ¶

submit_job async Alma: Submit a manual or scheduled job ¶

get_job_instances async Alma: Retrieve Job Instances ¶

get_job_instance async Alma: Retrieve Job Instance Details ¶

get_job_instance_matches async Alma: Retrieve Job Matching Details ¶

get_integration_profiles async Alma: Retrieve a list of Integration Profiles ¶

get_integration_profile async Alma: Retrieve an Integration Profile ¶

update_integration_profile async Alma: Update an Integration Profile ¶

create_integration_profile async Alma: Retrieve an Integration Profile ¶

client.config.code_tables¶

AlmaClientConfigCodeTablesNS ¶

get_code_tables async Alma: Retrieve Code Tables ¶

get_code_table async Alma: Retrieve Code-table ¶

update_code_table async Alma: Update Code-table ¶

`client.config`¶

`client.config.sets`¶

get_list `async` Alma: Retrieve a list of Sets ¶

get_set `async` Alma: Retrieve a Set ¶

create `async` Alma: Create a Set ¶

get_members `async` Alma: Retrieve Set Members ¶

delete_set `async` Alma: Delete a Set ¶

manage_members `async` Alma: Manage Members ¶

`client.config.libraries`¶

get_libraries `async` Alma: Retrieve Libraries ¶

get_circ_desks `async` Alma: Retrieve Circulation Desks ¶

get_locations `async` Alma: Retrieve Locations ¶

get_location `async` Alma: Retrieve Location ¶

get_departments `async` Alma: Retrieve Departments ¶

`client.config.letters`¶

get_letters `async` Alma: Retrieve Letters ¶

get_components `async` Alma: Retrieve Letters ¶

get_letter `async` Alma: Retrieve Letter ¶

update_letter `async` Alma: Update Letter ¶

`client.config.jobs`¶

get_jobs `async` Alma: Retrieve Jobs ¶

get_job `async` Alma: Retrieve Job Details ¶

submit_job `async` Alma: Submit a manual or scheduled job ¶

get_job_instances `async` Alma: Retrieve Job Instances ¶

get_job_instance `async` Alma: Retrieve Job Instance Details ¶

get_job_instance_matches `async` Alma: Retrieve Job Matching Details ¶

get_integration_profiles `async` Alma: Retrieve a list of Integration Profiles ¶

get_integration_profile `async` Alma: Retrieve an Integration Profile ¶

update_integration_profile `async` Alma: Update an Integration Profile ¶

create_integration_profile `async` Alma: Retrieve an Integration Profile ¶

`client.config.code_tables`¶

get_code_tables `async` Alma: Retrieve Code Tables ¶

get_code_table `async` Alma: Retrieve Code-table ¶

update_code_table `async` Alma: Update Code-table ¶