ForSURE.logins.endpoints

baseURL = 'logins'

Base URL for all requests

GET {baseURL}/clients
async def get_clients()

Retrieve a paginated list of clients with advanced filtering and search capabilities.

Parameters
  • search: Optional text search query to match against client names or company names.
  • country: Optional comma-separated list of country codes to filter by (e.g., "DE,FR,UK").
  • report_type: Optional comma-separated list of report types to filter by (e.g., "WEEE,Batteries").
  • pro: Optional comma-separated list of PRO names to filter by.
  • status: Optional comma-separated list of status values to filter by (e.g., "active,archived").
  • offset: Number of records to skip for pagination (default: 0).
  • limit: Maximum number of records to return (default: 10).
  • companyNameOnly: If True, search only matches against company names; otherwise searches all fields.
Returns

{
    "clients": [
        {
            "id": 123,
            "name": "ABC Corporation",
            "status": "active",
            "aliases": {"UK": "ABC Corp"},
            "notes": "Main client for WEEE compliance"
        }
    ],
    "total": 150,
    "offset": 0,
    "limit": 10
}

GET {baseURL}/clients/collective-accounts
async def get_collective_accounts()

Retrieve all collective accounts created by the organization. Collective accounts are master accounts created by EPR agencies for specific PROs that can be used by multiple clients. When credentials for a collective account are updated, all clients associated with that account automatically inherit the updated credentials.

Parameters
  • country: Optional country code to filter collective accounts by (e.g., "DE", "NL").
  • pro: Optional PRO name to filter collective accounts by (e.g., "Stichting Open").
Returns

[
    {
        "id": 5,
        "client_id": 10,
        "country": "NL",
        "report_type": "Packaging",
        "pro": "Stichting Open",
        "login": "collective@example.com",
        "client_name": "Collective Account - Stichting Open"
    }
]

GET {baseURL}/stats
async def get_clients_stats()

Retrieve aggregated statistics about the organization's client portfolio.

Returns

{
    "total_clients": 150,
    "by_country": {
        "DE": 45,
        "FR": 30,
        "NL": 25
    },
    "by_report_type": {
        "WEEE": 80,
        "Packaging": 60,
        "Batteries": 40
    },
    "by_status": {
        "active": 120,
        "archived": 30
    }
}

POST {baseURL}/clients
async def create_client()

Create a new client in the organization's portfolio.

Parameters
  • client_data: ClientAPI object containing client_name, status, shared, aliases, notes, client_organization, and collective_account.
Returns

{
    "id": 123,
    "name": "ABC Corporation",
    "status": "active",
    "shared": false,
    "aliases": {"UK": "ABC Corp", "DE": "ABC GmbH"},
    "notes": "Main client for WEEE compliance",
    "client_organization": null,
    "collective_account": false
}

PUT {baseURL}/clients/{client_id}
async def update_client()

Update an existing client's information.

Parameters
  • client_id: The unique identifier of the client to update.
  • client_data: ClientAPI object containing the fields to update. Only provided fields will be updated; omitted fields remain unchanged.
Returns

{
    "id": 123,
    "name": "ABC Corporation",
    "status": "archived",
    "shared": false,
    "aliases": {"UK": "ABC Corp"},
    "notes": "Client no longer active as of 2024",
    "client_organization": null,
    "collective_account": false
}

GET {baseURL}/clients/{client_id}
async def get_client()

Retrieve detailed information about a specific client.

Parameters
  • client_id: The unique identifier of the client to retrieve.
Returns

{
    "id": 123,
    "name": "ABC Corporation",
    "status": "active",
    "shared": false,
    "aliases": {"UK": "ABC Corp", "DE": "ABC GmbH"},
    "notes": "Main client for WEEE compliance",
    "client_organization": null,
    "collective_account": false
}

DELETE {baseURL}/clients/{client_id}
async def delete_client()

Delete a client from the organization's portfolio. This permanently removes a client and all associated credentials.

Parameters
  • client_id: The unique identifier of the client to delete.
Returns

{
    "message": "Client deleted successfully."
}

GET {baseURL}/clients/{client_id}/credentials/search
async def search_client_credentials()

Search and retrieve credentials for a specific client. Can also show missing credentials (credentials that should exist but don't) based on available report types and PROs.

Parameters
  • client_id: The unique identifier of the client.
  • search: Optional search query to filter credentials by country, report type, or PRO.
  • showMissing: If True, includes missing credentials in the results.
Returns

[
    {
        "id": 456,
        "country": "DE",
        "report_type": "WEEE",
        "pro": "Stiftung EAR",
        "login": "username@example.com",
        "password": "***",
        "registration_number": "DE123456",
        "status": "active",
        "notes": "Main credential"
    }
]

GET {baseURL}/clients/{client_id}/credentials/{country}
async def get_client_credentials()

Retrieve all credentials for a client in a specific country.

Parameters
  • client_id: The unique identifier of the client.
  • country: The country code (e.g., "DE", "FR", "UK") to filter credentials by.
Returns

[
    {
        "id": 456,
        "country": "DE",
        "report_type": "WEEE",
        "pro": "Stiftung EAR",
        "login": "username@example.com",
        "password": "secure_password",
        "registration_number": "DE123456",
        "notes": "Main credential",
        "interval": "quarterly",
        "extra_info": null
    }
]

POST {baseURL}/clients/{client_id}/credentials/{country}
async def create_client_credentials()

Create new login credentials for a client in a specific country. Credentials can be individual (stored directly) or linked to a collective account (using collective_account_id).

Parameters
  • client_id: The unique identifier of the client.
  • country: The country code where these credentials are valid.
  • body: ClientCredentials object containing report_types, pro, login, password, registration_number, collective_account, collective_account_id, notes, interval, and extra_info.
Returns

{
    "id": 456,
    "country": "DE",
    "report_type": "WEEE",
    "pro": "Stiftung EAR",
    "login": "username@example.com",
    "password": "secure_password",
    "registration_number": "DE123456",
    "notes": null,
    "interval": null,
    "extra_info": null,
    "collective_account": false,
    "collective_account_id": null
}

PUT {baseURL}/clients/{client_id}/credentials/{country}/{credential_id}
async def update_client_credentials()

Update existing login credentials for a client. Only provided fields will be updated; omitted fields remain unchanged.

Parameters
  • client_id: The unique identifier of the client.
  • country: The country code where these credentials are valid.
  • credential_id: The unique identifier of the credential to update.
  • body: ClientCredentials object containing the fields to update.
Returns

{
    "id": 456,
    "country": "DE",
    "report_type": "WEEE",
    "pro": "Stiftung EAR",
    "login": "username@example.com",
    "password": "new_secure_password",
    "registration_number": "DE123456",
    "notes": "Password updated on 2024-01-15",
    "interval": null,
    "extra_info": null
}

DELETE {baseURL}/clients/{client_id}/credentials/{country}/{credential_id}
async def delete_client_credentials()

Delete login credentials for a client.

Parameters
  • client_id: The unique identifier of the client.
  • country: The country code where these credentials are valid.
  • credential_id: The unique identifier of the credential to delete.
Returns

{
    "message": "Credential deleted successfully."
}

POST {baseURL}/clients/{client_id}/aliases
async def add_client_aliases()

Add an alias (alternative name) for a client. Aliases can be scoped to specific countries or apply globally.

Parameters
  • client_id: The unique identifier of the client.
  • body: ClientAlias object containing the alias to add.
Returns

{
    "id": 123,
    "name": "ABC Corporation",
    "status": "active",
    "aliases": {"UK": "ABC Corp", "DE": "ABC GmbH"},
    "notes": null
}

DELETE {baseURL}/clients/{client_id}/aliases/{alias}
async def remove_client_aliases()

Remove an alias from a client.

Parameters
  • client_id: The unique identifier of the client.
  • alias: The alias name to remove from the client.
Returns

{
    "message": "Alias removed successfully."
}

GET {baseURL}/report_types
async def get_report_types()

Retrieve available report types organized by country and PRO. Fetches the list of all available report types from the reporting API.

Returns

{
    "DE": {
        "Stiftung EAR": ["WEEE"]
    },
    "FR": {
        "Eco-Emballages": ["Packaging"]
    },
    "NL": {
        "Stichting Open": ["Packaging"]
    }
}

POST {baseURL}/clients/{client_id}/local-company-name/{country}
async def set_local_company_name()

Set the local company name for a client in a specific country.

Parameters
  • client_id: The unique identifier of the client.
  • country: The country code where this local company name applies.
  • body: LocalCompanyName object containing the local_company_name.
Returns

{
    "id": 123,
    "name": "ABC Corporation",
    "aliases": {"DE": "ABC GmbH"},
    "notes": null
}

GET {baseURL}/clients/{client_id}/local-company-name/{country}
async def get_local_company_name()

Retrieve the local company name for a client in a specific country.

Parameters
  • client_id: The unique identifier of the client.
  • country: The country code to retrieve the local company name for.
Returns

{
    "local_company_name": "ABC GmbH"
}

POST {baseURL}/clients/bulk-upload/preview
async def bulk_upload_clients_preview()

Preview the results of a bulk client upload without applying changes. This endpoint does not modify the database.

Parameters
  • csvData: List of CSV data rows (typically from a parsed CSV file).
  • fileId: List of file identifiers associated with the upload.
  • mapping: List of field mappings that define how CSV columns map to client data fields (e.g., ["name", "status", "country"]).
Returns

{
    "preview": true,
    "summary": {
        "would_create": 50,
        "would_update": 10,
        "errors": 2,
        "warnings": 5
    },
    "sample_data": [
        {
            "name": "Client 1",
            "status": "active"
        }
    ],
    "validation_results": {
        "valid": 48,
        "invalid": 2
    }
}

POST {baseURL}/clients/bulk-upload
async def bulk_upload_clients_execute()

Execute a bulk upload of clients from a CSV file. This endpoint modifies the database. Always use the preview endpoint first to verify the data.

Parameters
  • csvData: List of CSV data rows (typically from a parsed CSV file).
  • fileId: List of file identifiers associated with the upload.
  • mapping: List of field mappings that define how CSV columns map to client data fields (e.g., ["name", "status", "country"]).
Returns

{
    "created": 50,
    "updated": 10,
    "errors": 2,
    "summary": "Bulk upload completed successfully. 50 clients created, 10 clients updated, 2 errors encountered."
}