ForSURE.logins.endpoints

Base URL for all requests

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

This endpoint allows you to search and filter your organization's client portfolio with multiple criteria. Clients can be filtered by country, report type, PRO, status, and collective account status. Results are paginated for efficient data retrieval.

Parameters

search str, optional - Text search query to match against client names or company names.

country str, optional - Comma-separated list of country codes to filter by (e.g., "DE,FR,UK").

report_type str, optional - Comma-separated list of report types to filter by (e.g., "WEEE,Batteries").

pro str, optional - Comma-separated list of PRO names to filter by.

status str, optional - Comma-separated list of status values to filter by (e.g., "active,archived").

collective_account bool, optional - Filter by collective account status (True/False).

offset int, default 0 - Number of records to skip for pagination.

limit int, default 10 - Maximum number of records to return.

companyNameOnly bool, default False - If True, search only matches against company names; otherwise searches all fields.

Returns

dict

Response containing:

• clients list[dict] - List of client objects
• total int - Total number of clients matching the filters
• offset int - Current offset
• limit int - Current limit

Example

curl -X GET "https://api.example.com/saas/logins/clients?search=ABC&country=DE,FR&status=active&offset=0&limit=10" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
    "clients": [
        {
            "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
        }
    ],
    "total": 150,
    "offset": 0,
    "limit": 10
}

{
  "detail": "Failed to get client overview"
}

Note

Requires authentication. Results are filtered by the current user's organization. Multiple filter values can be provided as comma-separated strings.

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 str, optional - Country code to filter collective accounts by (e.g., "DE", "NL").

pro str, optional - PRO name to filter collective accounts by (e.g., "Stichting Open").

Returns

list[dict]

List of collective account objects, each containing:

• id int - Collective account ID
• client_id int - Client ID of the collective account
• country str - Country code
• report_type str - Report type (WEEE, Packaging, Batteries)
• pro str - PRO name
• login str - Login username
• client_name str - Name of the collective account

Example

curl -X GET "https://api.example.com/saas/logins/clients/collective-accounts?country=NL&pro=Stichting%20Open" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

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

{
  "detail": "Failed to get collective accounts"
}

Note

Requires authentication. Only returns collective accounts created by the current user's organization. Collective accounts allow multiple clients to share the same credentials, simplifying credential management.

Retrieve aggregated statistics about the organization's client portfolio.

This endpoint provides summary statistics about your client portfolio, including total client count, distribution by country, report type, and status. Useful for dashboards and reporting.

Returns

dict

Response containing:

• total_clients int - Total number of clients in the organization
• by_country dict[str, int] - Count of clients by country code
• by_report_type dict[str, int] - Count of clients by report type
• by_status dict[str, int] - Count of clients by status

Example

curl -X GET "https://api.example.com/saas/logins/stats" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
    "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
    }
}

{
  "detail": "Failed to get client stats"
}

Note

Requires authentication. Statistics are calculated based on the current user's organization. Counts may include duplicates if a client has multiple credentials across different countries or report types.

Create a new client in the organization's portfolio.

This endpoint creates a new client with the specified information. Clients represent companies or entities for which you manage EPR credentials and compliance data.

Parameters

client_data ClientAPI - Request object containing:

• client_name str - Name of the client
• status str, optional - Client status (e.g., "active", "archived")
• shared bool, optional - Whether the client is shared across organizations
• aliases dict[str, str], optional - Dictionary of country-specific aliases
• notes str, optional - Additional notes about the client
• client_organization str, optional - Organization of the client if it's a customer
• collective_account bool, optional - Whether this is a collective account

Returns

dict

Response containing the created client:

• id int - Client ID
• name str - Client name
• status str - Client status
• shared bool - Whether client is shared
• aliases dict - Client aliases
• notes str - Client notes
• client_organization str, optional - Client organization
• collective_account bool - Whether this is a collective account

Example

curl -X POST "https://api.example.com/saas/logins/clients" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "client_name": "ABC Corporation",
  "status": "active",
  "shared": false,
  "aliases": {"UK": "ABC Corp", "DE": "ABC GmbH"},
  "notes": "Main client for WEEE compliance"
}'

Response Example

{
    "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
}

{
  "detail": "Failed to create client"
}

Note

Requires authentication. The client will be created in the current user's organization. Client names should be unique within an organization.

Update an existing client's information.

This endpoint allows you to update client information. Only provided fields will be updated; omitted fields remain unchanged.

Parameters

client_id int - The unique identifier of the client to update.

client_data ClientAPI - Request object containing fields to update:

• client_name str, optional - New client name
• status str, optional - New status
• shared bool, optional - Whether client is shared
• aliases dict[str, str], optional - Updated aliases
• notes str, optional - Updated notes
• client_organization str, optional - Updated client organization
• collective_account bool, optional - Whether this is a collective account

Returns

dict

Response containing the updated client object with the same structure as create.

Example

curl -X PUT "https://api.example.com/saas/logins/clients/123" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "status": "archived",
  "notes": "Client no longer active as of 2024"
}'

Response Example

{
    "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
}

{
  "detail": "Failed to update client"
}

{
  "detail": "Client not found"
}

Note

Requires authentication. Only clients belonging to the current user's organization can be updated. Partial updates are supported - only include fields you want to change.

Retrieve detailed information about a specific client.

This endpoint retrieves complete information about a single client, including all its metadata, aliases, and status.

Parameters

client_id int - The unique identifier of the client to retrieve.

Returns

dict

Response containing the client object with the same structure as create/update. Returns empty object {} if client not found.

Example

curl -X GET "https://api.example.com/saas/logins/clients/123" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
    "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
}

{
  "detail": "Failed to get client"
}

Note

Requires authentication. Only clients belonging to the current user's organization can be retrieved. Returns empty object if client is not found or not accessible.

Delete a client from the organization's portfolio.

This endpoint permanently removes a client and all associated credentials. This action cannot be undone.

Parameters

client_id int - The unique identifier of the client to delete.

Returns

dict

Response containing:

• message str - Success message

Example

curl -X DELETE "https://api.example.com/saas/logins/clients/123" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

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

{
  "detail": "Failed to delete client"
}

{
  "detail": "Client not found"
}

Note

Requires authentication. Only clients belonging to the current user's organization can be deleted. This action permanently removes the client and all associated credentials. Use with caution.

Search and retrieve credentials for a specific client.

This endpoint retrieves credentials for a client with optional search filtering. Can also show missing credentials (credentials that should exist but don't) based on available report types and PROs for the organization.

Parameters

client_id int - The unique identifier of the client.

search str, optional - Search query to filter credentials by country, report type, or PRO.

showMissing bool, default False - If True, includes missing credentials in the results. Missing credentials are placeholders for credentials that should exist based on available report types and PROs but haven't been created yet.

Returns

list[dict]

List of credential objects, each containing:

• id int - Credential ID
• country str - Country code
• report_type str - Report type (WEEE, Packaging, Batteries)
• pro str - PRO name
• login str - Login username
• password str - Password (may be masked)
• registration_number str, optional - Registration number
• status str, optional - Credential status
• notes str, optional - Additional notes

Example

curl -X GET "https://api.example.com/saas/logins/clients/123/credentials/search?search=DE&showMissing=true" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

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

{
  "detail": "Failed to get client credentials"
}

Note

Requires authentication. Only credentials for clients belonging to the current user's organization can be retrieved. Passwords may be masked in responses for security.

Retrieve all credentials for a client in a specific country.

This endpoint retrieves all credentials associated with a client for a specific country. Useful for viewing all login credentials needed for a particular country's reporting requirements.

Parameters

client_id int - The unique identifier of the client.

country str - The country code (e.g., "DE", "FR", "UK") to filter credentials by.

Returns

list[dict]

List of credential objects for the specified country, each containing:

• id int - Credential ID
• country str - Country code
• report_type str - Report type (WEEE, Packaging, Batteries)
• pro str - PRO name
• login str - Login username
• password str - Password
• registration_number str, optional - Registration number
• notes str, optional - Additional notes
• interval str, optional - Reporting interval
• extra_info str, optional - Extra information

Example

curl -X GET "https://api.example.com/saas/logins/clients/123/credentials/DE" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

[
    {
        "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
    }
]

{
  "detail": "Failed to get client credentials"
}

Note

Requires authentication. Only credentials for clients belonging to the current user's organization can be retrieved. Returns empty list if no credentials exist for the specified country.

Create new login credentials for a client in a specific country.

This endpoint creates new login credentials for a client. Credentials can be individual (stored directly) or linked to a collective account (using collective_account_id). When linked to a collective account, credential updates are automatically inherited by all clients using that account.

Parameters

client_id int - The unique identifier of the client.

country str - The country code where these credentials are valid (e.g., "DE", "FR", "UK").

body ClientCredentials - Request object containing:

• report_types list[str] - List of report types (e.g., ["WEEE", "Packaging"])
• pro str - PRO name
• login str - Login username
• password str - Password
• registration_number str, optional - Registration number
• collective_account bool, optional - Whether this uses a collective account
• collective_account_id int, optional - ID of collective account to link to
• notes str, optional - Additional notes
• interval str, optional - Reporting interval
• extra_info str, optional - Extra information

Returns

dict

Response containing the created credential object with the same structure as get.

Example

curl -X POST "https://api.example.com/saas/logins/clients/123/credentials/DE" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "report_types": ["WEEE"],
  "pro": "Stiftung EAR",
  "login": "username@example.com",
  "password": "secure_password",
  "registration_number": "DE123456"
}'

Response Example

{
    "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
}

{
  "detail": "Failed to create client credentials"
}

Note

Requires authentication. Only credentials for clients belonging to the current user's organization can be created. If using a collective account, the collective_account_id must exist and belong to your organization.

Update existing login credentials for a client.

This endpoint allows you to update credential information. Only provided fields will be updated; omitted fields remain unchanged.

Parameters

client_id int - The unique identifier of the client.

country str - The country code where these credentials are valid.

credential_id int - The unique identifier of the credential to update.

body ClientCredentials - Request object containing fields to update. Same structure as create, but all fields are optional.

Returns

dict

Response containing the updated credential object with the same structure as get.

Example

curl -X PUT "https://api.example.com/saas/logins/clients/123/credentials/DE/456" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "password": "new_secure_password",
  "notes": "Password updated on 2024-01-15"
}'

Response Example

{
    "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
}

{
  "detail": "Failed to update client credentials"
}

Note

Requires authentication. Only credentials for clients belonging to the current user's organization can be updated. Partial updates are supported - only include fields you want to change.

Delete login credentials for a client.

This endpoint permanently removes login credentials for a client. This action cannot be undone.

Parameters

client_id int - The unique identifier of the client.

country str - The country code where these credentials are valid.

credential_id int - The unique identifier of the credential to delete.

Returns

dict

Response containing:

• message str - Success message

Example

curl -X DELETE "https://api.example.com/saas/logins/clients/123/credentials/DE/456" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

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

{
  "detail": "Failed to delete client credentials"
}

Note

Requires authentication. Only credentials for clients belonging to the current user's organization can be deleted. This action permanently removes the credential. Use with caution.

Add an alias (alternative name) for a client.

This endpoint adds an alias to a client. Aliases can be scoped to specific countries or apply globally. Useful for managing clients that have different names in different countries or jurisdictions.

Parameters

client_id int - The unique identifier of the client.

body _ClientAlias - Request object containing:

• alias str - The alias to add (format: "country:alias_name" for country-specific, or just "alias_name" for global)

Returns

dict

Response containing the updated client object with aliases included.

Example

curl -X POST "https://api.example.com/saas/logins/clients/123/aliases" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "alias": "DE:ABC GmbH"
}'

Response Example

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

{
  "detail": "Failed to add client aliases"
}

Note

Requires authentication. Only clients belonging to the current user's organization can be updated. Aliases are stored in the format "country:alias" for country-specific aliases, or just the alias name for global aliases.

Remove an alias from a client.

This endpoint removes an alias from a client. The alias should be provided in the same format as it was added (e.g., "DE:ABC GmbH" or "ABC Corp").

Parameters

client_id int - The unique identifier of the client.

alias str - The alias name to remove from the client (URL-encoded if needed).

Returns

dict

Response containing:

• message str - Success message

Example

curl -X DELETE "https://api.example.com/saas/logins/clients/123/aliases/DE%3AABC%20GmbH" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

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

{
  "detail": "Failed to remove client aliases"
}

Note

Requires authentication. Only clients belonging to the current user's organization can be updated. The alias parameter should be URL-encoded if it contains special characters like colons or spaces.

Retrieve available report types organized by country and PRO.

This endpoint fetches the list of all available report types from the reporting API, filtered by the organization's selected PROs. Report types are organized by country and PRO, making it easy to see what reporting options are available for each country-PRO combination.

Returns

dict

Response containing report types organized by country and PRO:

• {country_code} dict - Dictionary keyed by country code
  • {pro_name} list[str] - List of report types available for that PRO

Example

curl -X GET "https://api.example.com/saas/logins/report_types" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

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

{
  "detail": "Failed to get report types"
}

Note

Requires authentication. Results are filtered based on the organization's selected PROs. Only countries and PROs that are configured for your organization will appear in the results.

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

This endpoint sets a country-specific company name (alias) for a client. This is useful when a client operates under different names in different countries or jurisdictions.

Parameters

client_id int - The unique identifier of the client.

country str - The country code where this local company name applies (e.g., "DE", "FR").

body _LocalCompanyName - Request object containing:

• local_company_name str - The local company name to set

Returns

dict

Response containing the updated client object with the alias included.

Example

curl -X POST "https://api.example.com/saas/logins/clients/123/local-company-name/DE" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "local_company_name": "ABC GmbH"
}'

Response Example

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

{
  "detail": "Failed to get local company name"
}

Note

Requires authentication. This is essentially a convenience method for adding a country-specific alias. The local company name is stored as an alias in the format "country:local_company_name".

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

This endpoint retrieves the country-specific company name (alias) for a client. Returns the local name if one exists for the specified country.

Parameters

client_id int - The unique identifier of the client.

country str - The country code to retrieve the local company name for (e.g., "DE", "FR").

Returns

dict

Response containing:

• local_company_name str, optional - The local company name for the country, or null if no local name is set

Example

curl -X GET "https://api.example.com/saas/logins/clients/123/local-company-name/DE" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
    "local_company_name": "ABC GmbH"
}

{
    "local_company_name": null
}

{
  "detail": "Failed to get local company name"
}

Note

Requires authentication. Only clients belonging to the current user's organization can be accessed. Returns null if no local company name is set for the specified country.

Preview the results of a bulk client upload without applying changes.

This endpoint allows you to preview what would happen if you uploaded clients from a CSV file. It performs validation and shows what would be created or updated, but does not modify the database. Always use this endpoint before executing the actual bulk upload.

Parameters

csvData list[str] - List of CSV data rows (typically from a parsed CSV file). Each string represents a row of CSV data.

fileId list[str] - List of file identifiers associated with the upload. Used for tracking and error reporting.

mapping list[str] - List of field mappings that define how CSV columns map to client data fields (e.g., ["name", "status", "country"]). The order should match the CSV column order.

Returns

dict

Response containing preview information:

• preview bool - Always true for preview endpoint
• summary dict - Summary of what would happen:
  • would_create int - Number of clients that would be created
  • would_update int - Number of clients that would be updated
  • errors int - Number of errors encountered
  • warnings int - Number of warnings
• sample_data list[dict] - Sample of processed data
• validation_results dict - Validation statistics

Example

curl -X POST "https://api.example.com/saas/logins/clients/bulk-upload/preview" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "csvData=Client 1,active" \
-F "csvData=Client 2,archived" \
-F "fileId=file123" \
-F "mapping=name" \
-F "mapping=status"

Response Example

{
    "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
    }
}

{
  "detail": "Failed to bulk upload clients"
}

Note

Requires authentication. This endpoint does not modify the database. Always review the preview results before executing the actual bulk upload. The mapping array should match the CSV column order.

Execute a bulk upload of clients from a CSV file.

This endpoint performs the actual bulk upload of clients, modifying the database. Always use the preview endpoint first to verify the data before executing.

Parameters

csvData list[str] - List of CSV data rows (typically from a parsed CSV file). Each string represents a row of CSV data.

fileId list[str] - List of file identifiers associated with the upload. Used for tracking and error reporting.

mapping list[str] - List of field mappings that define how CSV columns map to client data fields (e.g., ["name", "status", "country"]). The order should match the CSV column order.

Returns

dict

Response containing upload results:

• created int - Number of clients created
• updated int - Number of clients updated
• errors int - Number of errors encountered
• summary str - Summary message describing the results

Example

curl -X POST "https://api.example.com/saas/logins/clients/bulk-upload" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "csvData=Client 1,active" \
-F "csvData=Client 2,archived" \
-F "fileId=file123" \
-F "mapping=name" \
-F "mapping=status"

Response Example

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

{
  "detail": "Failed to bulk upload clients"
}

Note

Requires authentication. This endpoint modifies the database. Always use the preview endpoint first to verify the data. The mapping array should match the CSV column order. Errors may occur for individual rows, but the upload will continue processing other rows.