Agents

Access via client.agents.

signtraker.agents.AgentsClient

AgentsClient(api_key: Optional[str] = None, base_url: Optional[str] = None, *, subdomain: Optional[str] = None, timeout_seconds: Optional[float] = None, max_retries: Optional[int] = None, retry_backoff_seconds: Optional[float] = None)

Bases: BaseClient

Client for the /api/agents endpoints.

Source code in signtraker/base_client.py

def __init__(
    self,
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    *,
    subdomain: Optional[str] = None,
    timeout_seconds: Optional[float] = None,
    max_retries: Optional[int] = None,
    retry_backoff_seconds: Optional[float] = None,
) -> None:
    """Initialize the base client.

    The base URL is resolved from the first available of: ``base_url``,
    ``subdomain`` (expanded to ``https://{subdomain}.signtraker.com``), the
    ``SIGNTRAKER_BASE_URL`` env var, or the ``SIGNTRAKER_SUBDOMAIN`` env var.

    Args:
        api_key: API key. Falls back to the ``SIGNTRAKER_API_KEY`` env var.
        base_url: Full API base URL (e.g.
            ``"https://acme.signtraker.com"``). Overrides ``subdomain``.
        subdomain: Tenant subdomain used to build the base URL when
            ``base_url`` is not provided.
        timeout_seconds: Per-request timeout. Falls back to env/default.
        max_retries: Retry attempts for transient failures.
        retry_backoff_seconds: Base backoff between retries (exponential).

    Raises:
        AuthenticationError: If no API key can be resolved.
        SignTrakerConfigError: If no base URL or subdomain can be resolved.
    """
    self.api_key = api_key or _getenv_with_alias(ENV_API_KEY, ENV_API_KEY_ALT)
    if not self.api_key:
        raise AuthenticationError(
            "API key is required. Set SIGNTRAKER_API_KEY or pass api_key."
        )
    self.base_url = self._resolve_base_url(base_url, subdomain)
    self.timeout_seconds = (
        float(timeout_seconds)
        if timeout_seconds is not None
        else _parse_env_float(ENV_TIMEOUT_SECONDS, DEFAULT_TIMEOUT_SECONDS)
    )
    self.max_retries = (
        int(max_retries)
        if max_retries is not None
        else _parse_env_int(ENV_MAX_RETRIES, DEFAULT_MAX_RETRIES)
    )
    self.retry_backoff_seconds = (
        float(retry_backoff_seconds)
        if retry_backoff_seconds is not None
        else _parse_env_float(
            ENV_RETRY_BACKOFF_SECONDS, DEFAULT_RETRY_BACKOFF_SECONDS
        )
    )
    self.session = requests.Session()
    self.session.headers.update(
        {
            "Authorization": f"ST-API {self.api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        }
    )

list_agents

list_agents(*, email: Optional[str] = None, filter: Optional[str] = None, top: Optional[int] = None, skip: Optional[int] = None, orderby: Optional[ODataValue] = None, select: Optional[ODataValue] = None) -> List[Dict[str, Any]]

List agents, optionally filtered, sorted, and paged.

Parameters:

Name	Type	Description	Default
email	Optional[str]	Find an agent by exact email address.	None
filter	Optional[str]	OData $filter expression (e.g. "LastName eq 'Smith'").	None
top	Optional[int]	OData $top (maximum number of records to return).	None
skip	Optional[int]	OData $skip (number of records to skip).	None
orderby	Optional[ODataValue]	OData $orderby value or sequence of fields.	None
select	Optional[ODataValue]	OData $select value or sequence of fields.	None

Returns:

Type	Description
List[Dict[str, Any]]	The list of matching agent records.

Raises:

Type	Description
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/agents.py

def list_agents(
    self,
    *,
    email: Optional[str] = None,
    filter: Optional[str] = None,
    top: Optional[int] = None,
    skip: Optional[int] = None,
    orderby: Optional[ODataValue] = None,
    select: Optional[ODataValue] = None,
) -> List[Dict[str, Any]]:
    """List agents, optionally filtered, sorted, and paged.

    Args:
        email: Find an agent by exact email address.
        filter: OData ``$filter`` expression (e.g. ``"LastName eq 'Smith'"``).
        top: OData ``$top`` (maximum number of records to return).
        skip: OData ``$skip`` (number of records to skip).
        orderby: OData ``$orderby`` value or sequence of fields.
        select: OData ``$select`` value or sequence of fields.

    Returns:
        The list of matching agent records.

    Raises:
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    params = build_odata_params(
        filter=filter,
        top=top,
        skip=skip,
        orderby=orderby,
        select=select,
        extra={"email": email},
    )
    return cast(List[Dict[str, Any]], self.get("api/agents", params))

get_agent

get_agent(agent_id: int) -> Dict[str, Any]

Get a single agent by ID.

Parameters:

Name	Type	Description	Default
agent_id	int	Unique identifier of the agent.	required

Returns:

Type	Description
Dict[str, Any]	The agent record.

Raises:

Type	Description
NotFoundError	If the agent does not exist.
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/agents.py

def get_agent(self, agent_id: int) -> Dict[str, Any]:
    """Get a single agent by ID.

    Args:
        agent_id: Unique identifier of the agent.

    Returns:
        The agent record.

    Raises:
        NotFoundError: If the agent does not exist.
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    return cast(Dict[str, Any], self.get(f"api/agents/{agent_id}"))

create_agent

create_agent(agent: Dict[str, Any]) -> Dict[str, Any]

Create an agent.

Parameters:

Name	Type	Description	Default
agent	Dict[str, Any]	The agent payload. Required fields include UserName, Email, FirstName, LastName, CellularPhone, PaymentMode, and an Office reference.	required

Returns:

Type	Description
Dict[str, Any]	The created agent record.

Raises:

Type	Description
ValidationError	If the payload is invalid.
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/agents.py

def create_agent(self, agent: Dict[str, Any]) -> Dict[str, Any]:
    """Create an agent.

    Args:
        agent: The agent payload. Required fields include ``UserName``,
            ``Email``, ``FirstName``, ``LastName``, ``CellularPhone``,
            ``PaymentMode``, and an ``Office`` reference.

    Returns:
        The created agent record.

    Raises:
        ValidationError: If the payload is invalid.
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    return cast(Dict[str, Any], self.post("api/agents", json_data=agent))

update_agent

update_agent(agent_id: int, changes: Dict[str, Any]) -> Dict[str, Any]

Update an agent using a JSON Merge Patch.

Only the fields present in changes are modified; omitted fields remain unchanged. You may not convert an agent to/from a manager with this method, and synced National Account agents cannot be updated directly.

Parameters:

Name	Type	Description	Default
agent_id	int	Unique identifier of the agent to update.	required
changes	Dict[str, Any]	The partial agent payload to merge.	required

Returns:

Type	Description
Dict[str, Any]	The updated agent record.

Raises:

Type	Description
NotFoundError	If the agent does not exist.
ValidationError	If the payload is invalid.
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/agents.py

def update_agent(self, agent_id: int, changes: Dict[str, Any]) -> Dict[str, Any]:
    """Update an agent using a JSON Merge Patch.

    Only the fields present in ``changes`` are modified; omitted fields
    remain unchanged. You may not convert an agent to/from a manager with
    this method, and synced National Account agents cannot be updated
    directly.

    Args:
        agent_id: Unique identifier of the agent to update.
        changes: The partial agent payload to merge.

    Returns:
        The updated agent record.

    Raises:
        NotFoundError: If the agent does not exist.
        ValidationError: If the payload is invalid.
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    return cast(
        Dict[str, Any],
        self.patch(
            f"api/agents/{agent_id}",
            json_data=changes,
            content_type="application/merge-patch+json",
        ),
    )

activate_agent

activate_agent(agent_id: int) -> Dict[str, Any]

Activate an agent.

Parameters:

Name	Type	Description	Default
agent_id	int	Unique identifier of the agent to activate.	required

Returns:

Type	Description
Dict[str, Any]	The parsed response payload (empty when the API returns no body).

Raises:

Type	Description
NotFoundError	If the agent does not exist.
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/agents.py

def activate_agent(self, agent_id: int) -> Dict[str, Any]:
    """Activate an agent.

    Args:
        agent_id: Unique identifier of the agent to activate.

    Returns:
        The parsed response payload (empty when the API returns no body).

    Raises:
        NotFoundError: If the agent does not exist.
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    return cast(
        Dict[str, Any],
        self.post("api/agents/activate", params={"id": agent_id}),
    )

deactivate_agent

deactivate_agent(agent_id: int) -> Dict[str, Any]

Deactivate an agent.

Parameters:

Name	Type	Description	Default
agent_id	int	Unique identifier of the agent to deactivate.	required

Returns:

Type	Description
Dict[str, Any]	The parsed response payload (empty when the API returns no body).

Raises:

Type	Description
NotFoundError	If the agent does not exist.
AuthenticationError	If the API key is invalid.
SignTrakerError	For other API errors.

Source code in signtraker/agents.py

def deactivate_agent(self, agent_id: int) -> Dict[str, Any]:
    """Deactivate an agent.

    Args:
        agent_id: Unique identifier of the agent to deactivate.

    Returns:
        The parsed response payload (empty when the API returns no body).

    Raises:
        NotFoundError: If the agent does not exist.
        AuthenticationError: If the API key is invalid.
        SignTrakerError: For other API errors.
    """
    return cast(
        Dict[str, Any],
        self.post("api/agents/deactivate", params={"id": agent_id}),
    )