Skip to content

Providers

Resource

ProvidersResource

Operations on provider accounts.

Source code in src/assured/resources/providers.py 
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
class ProvidersResource:
    """Operations on provider accounts."""

    def __init__(self, client: AssuredClient) -> None:
        self._client = client
        self._npi_cache: dict[str, Provider] = {}
        self._npi_cache_time: float = 0.0

    # ---- List ----

    async def list(self, params: ProviderListParams | None = None, **kwargs: Any) -> list[Provider]:
        raw_params = params.model_dump(exclude_none=False) if params else {}
        raw_params.update(kwargs)
        data = await self._client._get_page(_LIST_PATH, params=raw_params)
        return [Provider.model_validate(item) for item in data.get("results", [])]

    async def list_all(self, params: ProviderListParams | None = None, **kwargs: Any) -> list[Provider]:
        raw_params = params.model_dump(exclude_none=False) if params else {}
        raw_params.update(kwargs)
        records = await self._client._get_all_pages(_LIST_PATH, params=raw_params)
        return [Provider.model_validate(item) for item in records]

    async def list_df(self, params: ProviderListParams | None = None, **kwargs: Any) -> pd.DataFrame:
        raw_params = params.model_dump(exclude_none=False) if params else {}
        raw_params.update(kwargs)
        records = await self._client._get_all_pages(_LIST_PATH, params=raw_params)
        return self._client.to_dataframe(records)

    # ---- Get ----

    async def get(self, provider_id: str) -> Provider:
        """Fetch a single provider by account ID.

        Uses the list endpoint filtered by ``id_in`` and returns the
        first (and only) match.
        """
        results = await self.list(ProviderListParams(id_in=provider_id))
        if not results:
            from assured.exceptions import AssuredNotFoundError

            raise AssuredNotFoundError(
                404,
                f"No provider found with id={provider_id}",
                url=_LIST_PATH,
            )
        return results[0]

    async def get_profile_id(self, provider_id: str) -> str:
        """Resolve a provider account ID → provider_profile_id.

        Many profile endpoints (personal-info, certifications, licenses,
        insurance, etc.) require the ``provider_profile_id`` rather than
        the account ``id``.  This helper performs the lookup.
        """
        provider = await self.get(provider_id)
        if not provider.provider_profile_id:
            from assured.exceptions import AssuredAPIError

            raise AssuredAPIError(
                422,
                f"Provider {provider_id} has no profile ID",
                url=_LIST_PATH,
            )
        return provider.provider_profile_id

    async def get_by_npi(self, npi: str) -> Provider:
        """Fetch a single provider by their NPI.

        Since there is no native endpoint for NPI lookup, this pulls the
        full provider list and caches it for 5 minutes to optimize
        subsequent identical calls.
        """
        import time

        # Cache validity for 300 seconds (5 minutes)
        if time.time() - self._npi_cache_time > 300:
            all_providers = await self.list_all()
            self._npi_cache = {p.npi: p for p in all_providers if getattr(p, "npi", None)}
            self._npi_cache_time = time.time()

        provider = self._npi_cache.get(npi)
        if not provider:
            from assured.exceptions import AssuredNotFoundError

            raise AssuredNotFoundError(
                404,
                f"No provider found across the company with NPI={npi}",
                url=_LIST_PATH,
            )
        return provider

    # ---- Invite ----

    async def invite(self, providers: list[ProviderInvite]) -> list[dict[str, Any]]:
        """Invite one or more providers to the platform."""
        payload = [p.model_dump(mode="json", exclude_none=False) for p in providers]
        return await self._client._post(_INVITE_PATH, json=payload)

    # ---- CAQH Import ----

    async def import_with_caqh(self, data: ProviderCAQHImport) -> dict[str, Any]:
        """Import a single provider using CAQH credentials."""
        return await self._client._post(_CAQH_PATH, json=data.model_dump(mode="json", exclude_none=False))

    # ---- Create ----

    async def create(self, data: ProviderCreate) -> dict[str, Any]:
        """Create a new provider (without CAQH)."""
        return await self._client._post(_CREATE_PATH, json=data.model_dump(mode="json", exclude_none=False))

    # ---- Practice Locations ----

    async def list_not_in_practice_location(
        self, practice_location: str, params: ProviderListParams | None = None, **kwargs: Any
    ) -> list[Provider]:
        """List providers not associated with a specific practice location."""
        raw_params = params.model_dump(exclude_none=False) if params else {}
        raw_params.update(kwargs)
        raw_params["practice_location"] = practice_location
        data = await self._client._get_page(_NOT_IN_PRACTICE_LOC_PATH, params=raw_params)
        return [Provider.model_validate(item) for item in data.get("results", [])]

    async def list_all_not_in_practice_location(
        self, practice_location: str, params: ProviderListParams | None = None, **kwargs: Any
    ) -> list[Provider]:
        """List all providers not associated with a specific practice location."""
        raw_params = params.model_dump(exclude_none=False) if params else {}
        raw_params.update(kwargs)
        raw_params["practice_location"] = practice_location
        records = await self._client._get_all_pages(_NOT_IN_PRACTICE_LOC_PATH, params=raw_params)
        return [Provider.model_validate(item) for item in records]

    async def list_not_in_practice_location_df(
        self, practice_location: str, params: ProviderListParams | None = None, **kwargs: Any
    ) -> pd.DataFrame:
        """List all providers not associated with a specific practice location as a DataFrame."""
        raw_params = params.model_dump(exclude_none=False) if params else {}
        raw_params.update(kwargs)
        raw_params["practice_location"] = practice_location
        records = await self._client._get_all_pages(_NOT_IN_PRACTICE_LOC_PATH, params=raw_params)
        return self._client.to_dataframe(records)

    async def add_to_practice_location(self, data: PracticeLocationProvidersCreate) -> dict[str, Any]:
        """Associate multiple providers with a practice location."""
        return await self._client._post(
            _PRACTICE_LOC_PROVIDERS_PATH, json=data.model_dump(mode="json", exclude_none=False)
        )

get(provider_id) async

Fetch a single provider by account ID.

Uses the list endpoint filtered by id_in and returns the first (and only) match.

Source code in src/assured/resources/providers.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
async def get(self, provider_id: str) -> Provider:
    """Fetch a single provider by account ID.

    Uses the list endpoint filtered by ``id_in`` and returns the
    first (and only) match.
    """
    results = await self.list(ProviderListParams(id_in=provider_id))
    if not results:
        from assured.exceptions import AssuredNotFoundError

        raise AssuredNotFoundError(
            404,
            f"No provider found with id={provider_id}",
            url=_LIST_PATH,
        )
    return results[0]

get_profile_id(provider_id) async

Resolve a provider account ID → provider_profile_id.

Many profile endpoints (personal-info, certifications, licenses, insurance, etc.) require the provider_profile_id rather than the account id. This helper performs the lookup.

Source code in src/assured/resources/providers.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
async def get_profile_id(self, provider_id: str) -> str:
    """Resolve a provider account ID → provider_profile_id.

    Many profile endpoints (personal-info, certifications, licenses,
    insurance, etc.) require the ``provider_profile_id`` rather than
    the account ``id``.  This helper performs the lookup.
    """
    provider = await self.get(provider_id)
    if not provider.provider_profile_id:
        from assured.exceptions import AssuredAPIError

        raise AssuredAPIError(
            422,
            f"Provider {provider_id} has no profile ID",
            url=_LIST_PATH,
        )
    return provider.provider_profile_id

get_by_npi(npi) async

Fetch a single provider by their NPI.

Since there is no native endpoint for NPI lookup, this pulls the full provider list and caches it for 5 minutes to optimize subsequent identical calls.

Source code in src/assured/resources/providers.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
async def get_by_npi(self, npi: str) -> Provider:
    """Fetch a single provider by their NPI.

    Since there is no native endpoint for NPI lookup, this pulls the
    full provider list and caches it for 5 minutes to optimize
    subsequent identical calls.
    """
    import time

    # Cache validity for 300 seconds (5 minutes)
    if time.time() - self._npi_cache_time > 300:
        all_providers = await self.list_all()
        self._npi_cache = {p.npi: p for p in all_providers if getattr(p, "npi", None)}
        self._npi_cache_time = time.time()

    provider = self._npi_cache.get(npi)
    if not provider:
        from assured.exceptions import AssuredNotFoundError

        raise AssuredNotFoundError(
            404,
            f"No provider found across the company with NPI={npi}",
            url=_LIST_PATH,
        )
    return provider

invite(providers) async

Invite one or more providers to the platform.

Source code in src/assured/resources/providers.py 
122
123
124
125
async def invite(self, providers: list[ProviderInvite]) -> list[dict[str, Any]]:
    """Invite one or more providers to the platform."""
    payload = [p.model_dump(mode="json", exclude_none=False) for p in providers]
    return await self._client._post(_INVITE_PATH, json=payload)

import_with_caqh(data) async

Import a single provider using CAQH credentials.

Source code in src/assured/resources/providers.py 
129
130
131
async def import_with_caqh(self, data: ProviderCAQHImport) -> dict[str, Any]:
    """Import a single provider using CAQH credentials."""
    return await self._client._post(_CAQH_PATH, json=data.model_dump(mode="json", exclude_none=False))

create(data) async

Create a new provider (without CAQH).

Source code in src/assured/resources/providers.py 
135
136
137
async def create(self, data: ProviderCreate) -> dict[str, Any]:
    """Create a new provider (without CAQH)."""
    return await self._client._post(_CREATE_PATH, json=data.model_dump(mode="json", exclude_none=False))

list_not_in_practice_location(practice_location, params=None, **kwargs) async

List providers not associated with a specific practice location.

Source code in src/assured/resources/providers.py 
141
142
143
144
145
146
147
148
149
async def list_not_in_practice_location(
    self, practice_location: str, params: ProviderListParams | None = None, **kwargs: Any
) -> list[Provider]:
    """List providers not associated with a specific practice location."""
    raw_params = params.model_dump(exclude_none=False) if params else {}
    raw_params.update(kwargs)
    raw_params["practice_location"] = practice_location
    data = await self._client._get_page(_NOT_IN_PRACTICE_LOC_PATH, params=raw_params)
    return [Provider.model_validate(item) for item in data.get("results", [])]

list_all_not_in_practice_location(practice_location, params=None, **kwargs) async

List all providers not associated with a specific practice location.

Source code in src/assured/resources/providers.py 
151
152
153
154
155
156
157
158
159
async def list_all_not_in_practice_location(
    self, practice_location: str, params: ProviderListParams | None = None, **kwargs: Any
) -> list[Provider]:
    """List all providers not associated with a specific practice location."""
    raw_params = params.model_dump(exclude_none=False) if params else {}
    raw_params.update(kwargs)
    raw_params["practice_location"] = practice_location
    records = await self._client._get_all_pages(_NOT_IN_PRACTICE_LOC_PATH, params=raw_params)
    return [Provider.model_validate(item) for item in records]

list_not_in_practice_location_df(practice_location, params=None, **kwargs) async

List all providers not associated with a specific practice location as a DataFrame.

Source code in src/assured/resources/providers.py 
161
162
163
164
165
166
167
168
169
async def list_not_in_practice_location_df(
    self, practice_location: str, params: ProviderListParams | None = None, **kwargs: Any
) -> pd.DataFrame:
    """List all providers not associated with a specific practice location as a DataFrame."""
    raw_params = params.model_dump(exclude_none=False) if params else {}
    raw_params.update(kwargs)
    raw_params["practice_location"] = practice_location
    records = await self._client._get_all_pages(_NOT_IN_PRACTICE_LOC_PATH, params=raw_params)
    return self._client.to_dataframe(records)

add_to_practice_location(data) async

Associate multiple providers with a practice location.

Source code in src/assured/resources/providers.py 
171
172
173
174
175
async def add_to_practice_location(self, data: PracticeLocationProvidersCreate) -> dict[str, Any]:
    """Associate multiple providers with a practice location."""
    return await self._client._post(
        _PRACTICE_LOC_PROVIDERS_PATH, json=data.model_dump(mode="json", exclude_none=False)
    )

Models

Provider

Bases: BaseModel

A provider account.

Source code in src/assured/models/providers.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
class Provider(BaseModel):
    """A provider account."""

    id: str | None = None
    email: str | None = None
    first_name: str | None = None
    middle_name: str | None = None
    last_name: str | None = None
    npi: str | None = None
    full_name: str | None = None
    provider_profile_id: str | None = None
    profile_completeness_percentage: float | None = None
    is_active: bool | None = None
    user_type: str | None = None

ProviderCreate

Bases: BaseModel

Payload for creating a provider without CAQH.

Source code in src/assured/models/providers.py 
63
64
65
66
67
68
69
70
71
72
73
class ProviderCreate(BaseModel):
    """Payload for creating a provider without CAQH."""

    email: str
    first_name: str
    last_name: str
    client: str
    document_url: str
    document_type: str
    provider_practice_locations: list[str] | None = None
    org_joining_date: date | None = None

ProviderInvite

Bases: BaseModel

Payload for inviting a provider.

Source code in src/assured/models/providers.py 
41
42
43
44
45
46
47
48
49
class ProviderInvite(BaseModel):
    """Payload for inviting a provider."""

    email: str
    first_name: str
    last_name: str
    provider_practice_locations: list[str] | None = None
    client: str | None = None
    org_joining_date: date | None = None

ProviderCAQHImport

Bases: BaseModel

Payload for importing a provider via CAQH.

Source code in src/assured/models/providers.py 
52
53
54
55
56
57
58
59
60
class ProviderCAQHImport(BaseModel):
    """Payload for importing a provider via CAQH."""

    email: str
    first_name: str
    last_name: str
    caqh_username: str
    caqh_password: str
    provider_practice_locations: list[str] | None = None

ProviderListParams

Bases: BaseModel

Query parameters for the providers list endpoint.

Source code in src/assured/models/providers.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
class ProviderListParams(BaseModel):
    """Query parameters for the providers list endpoint."""

    email: str | None = None
    first_name: str | None = None
    id_in: str | None = None
    last_name: str | None = None
    limit: int | None = None
    npi: str | None = None
    offset: int | None = None
    ordering: str | None = None
    profile_completeness: bool | None = None
    search: str | None = None