> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/sdk/python/fetch
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# client.fetch

> Fetch cached or live person and company profiles with the Python SDK, check profile status, and inspect each method, return type, error and cost.

- Last verified: 2026-11-04

Read cached person or company profiles, check availability, or start a live fetch job.

| Method | Endpoint | Cost |
| ------ | -------- | ---- |
| [`person()`](#person) | [POST /v2/fetch/persons](https://docs.reversecontact.com/endpoints/fetch-profile) | 1 credit when the profile is found in the cache. A 404 is free. |
| [`person_live()`](#person_live) | [POST /v2/fetch/persons/live](https://docs.reversecontact.com/endpoints/fetch-profile-live) | 2 credits per request, consumed when the job is created. |
| [`check_person()`](#check_person) | [POST /v2/fetch/persons/check](https://docs.reversecontact.com/endpoints/check-person) | Free. Needs at least 2 credits in the workspace: below that, 402 NO_CREDITS. |
| [`company()`](#company) | [POST /v2/fetch/companies](https://docs.reversecontact.com/endpoints/fetch-company) | 1 credit when the company is found in the cache. A 404 is free. |
| [`company_live()`](#company_live) | [POST /v2/fetch/companies/live](https://docs.reversecontact.com/endpoints/fetch-company-live) | 2 credits per request, consumed when the job is created. |
| [`check_company()`](#check_company) | [POST /v2/fetch/companies/check](https://docs.reversecontact.com/endpoints/check-company) | Free. Needs at least 2 credits in the workspace: below that, 402 NO_CREDITS. |

## Calling conventions

Examples assume `RC_API_KEY` is set. Replace example ids with ids returned by your own requests. Signatures show the published 0.3.0 synchronous methods. Use the same arguments with the [Python async client](https://docs.reversecontact.com/sdk/python/async-client).

`models` refers to `reversecontact.types`. `NOT_GIVEN` and `NotGiven` are the SDK's internal markers for omitted arguments. Leave these arguments out of your calls. For API body parameters, passing `None` sends an explicit null. Transport options use `None` to inherit their defaults. `Timeout` means a number of seconds or `httpx.Timeout`. Supply parameters marked **Required** to Python or to the API, even when the generated signature permits omission.

JSON response objects expose `data`, `quotas`, `metadata` and `http_response`. Check optional fields for `None`. See [First call](https://docs.reversecontact.com/sdk/python/first-call) for the response envelope. CSV methods return text and iterators yield items.

HTTP failures raise an `APIError` subclass based on the response: `BadRequestError`, `AuthenticationError`, `InsufficientCreditsError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `GoneError`, `UnprocessableEntityError`, `RateLimitError`, `DailyLimitError`, `KeyCreditLimitError`, `UnavailableForLegalReasonsError` or `InternalServerError`. See the [error mapping and retry rules](https://docs.reversecontact.com/sdk/python/errors-and-retries).

## person

Supply a person `url` or `id`.

**Python SDK**

```python [Python SDK]
def person(
    *,
    url: str | NotGiven | None = NOT_GIVEN,
    id: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.PersonFull] | None: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `url` | `str \| NotGiven \| None` | **Required for the selected strategy.** Public Social profile URL (e.g. `https://social.com/in/janedoe`). Required unless `id` is given. |
| `id` | `str \| NotGiven \| None` | **Required for the selected strategy.** Reverse Contact person id from a previous response (e.g. `prs_01jbd5vewyenebxgaz869ffe5t`). Required unless `url` is given. |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.PersonFull] | None`. `data` is the cached person profile. A no-match lookup returns `None` at no credit cost.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. No-match 404 responses return `None`. Other 404 responses raise `NotFoundError`. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.fetch.person(url="https://social.com/in/janedoe")
    print(result.data if result is not None else None)
```
## person_live

Start an asynchronous enrichment job with a person `url` or `id`.

**Python SDK**

```python [Python SDK]
def person_live(
    *,
    url: str | NotGiven | None = NOT_GIVEN,
    id: str | NotGiven | None = NOT_GIVEN,
    webhook_url: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Job[models.PersonFull]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `url` | `str \| NotGiven \| None` | **Required for the selected strategy.** Public Social profile URL (e.g. `https://social.com/in/janedoe`). Provide exactly one of `url` or `id`. |
| `id` | `str \| NotGiven \| None` | **Required for the selected strategy.** Reverse Contact person id (`prs_…`). The gateway resolves it to the current Social public slug before starting the scrape. |
| `webhook_url` | `str \| NotGiven \| None` | Optional. HTTPS push URL for webhook delivery. Omit this field to retrieve the result via [polling](https://docs.reversecontact.com/guides/polling) (recommended). See the [Webhooks guide](https://docs.reversecontact.com/guides/webhooks) when you need push delivery. |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Job[models.PersonFull]`. A job acknowledgement with `id`, `data`, `quotas`, `metadata`, `http_response` and `replayed`. Save `job.id` before waiting. Call `job.wait()` to get `Result[JobSnapshot[T]]` with the final value in `data.result`. See [Async jobs](https://docs.reversecontact.com/sdk/python/async-jobs) for details.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options or a missing job id in the acknowledgement. `wait()` raises `JobFailedError` for an errored job and `JobTimeoutError` when its overall deadline expires. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    job = client.fetch.person_live(url="https://social.com/in/janedoe")
    print("Save this job id:", job.id)
    done = job.wait()
    print(done.data.result if done.data else None)
```
## check_person

Supply a person `url` or `id`. The call is free but requires at least 2 credits in the workspace.

**Python SDK**

```python [Python SDK]
def check_person(
    *,
    url: str | NotGiven | None = NOT_GIVEN,
    id: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.CheckPersonData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `url` | `str \| NotGiven \| None` | **Required for the selected strategy.** Public Social profile URL (e.g. `https://social.com/in/janedoe`). Required unless `id` is given. |
| `id` | `str \| NotGiven \| None` | **Required for the selected strategy.** Reverse Contact person id from a previous response (e.g. `prs_01jbd5vewyenebxgaz869ffe5t`). Required unless `url` is given. |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.CheckPersonData]`. `data` contains `exists`, `last_update`, `experience_count`, `skill_count` and `school_count`.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.fetch.check_person(url="https://social.com/in/janedoe")
    print(result.data if result is not None else None)
```
## company

Supply a company `url` or `id`.

**Python SDK**

```python [Python SDK]
def company(
    *,
    url: str | NotGiven | None = NOT_GIVEN,
    id: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.CompanyFull] | None: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `url` | `str \| NotGiven \| None` | **Required for the selected strategy.** Public Social company URL (e.g. `https://social.com/company/acme-corp`). Required unless `id` is given. |
| `id` | `str \| NotGiven \| None` | **Required for the selected strategy.** Reverse Contact company id from a previous response (e.g. `com_01jbd5vewyenebxgaz869ffe5t`). Required unless `url` is given. |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.CompanyFull] | None`. `data` is the cached company profile. A no-match lookup returns `None` at no credit cost.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. No-match 404 responses return `None`. Other 404 responses raise `NotFoundError`. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.fetch.company(url="https://social.com/company/acme")
    print(result.data if result is not None else None)
```
## company_live

Start an asynchronous enrichment job with a company `url` or `id`.

**Python SDK**

```python [Python SDK]
def company_live(
    *,
    url: str | NotGiven | None = NOT_GIVEN,
    id: str | NotGiven | None = NOT_GIVEN,
    webhook_url: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Job[models.CompanyFull]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `url` | `str \| NotGiven \| None` | **Required for the selected strategy.** Public Social company URL (e.g. `https://social.com/company/acme-corp`). Provide exactly one of `url` or `id`. |
| `id` | `str \| NotGiven \| None` | **Required for the selected strategy.** Reverse Contact company id (`com_…`). The gateway resolves it to the current Social public slug before starting the scrape. |
| `webhook_url` | `str \| NotGiven \| None` | Optional. HTTPS push URL for webhook delivery. Omit this field to retrieve the result via [polling](https://docs.reversecontact.com/guides/polling) (recommended). See the [Webhooks guide](https://docs.reversecontact.com/guides/webhooks) when you need push delivery. |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Job[models.CompanyFull]`. A job acknowledgement with `id`, `data`, `quotas`, `metadata`, `http_response` and `replayed`. Save `job.id` before waiting. Call `job.wait()` to get `Result[JobSnapshot[T]]` with the final value in `data.result`. See [Async jobs](https://docs.reversecontact.com/sdk/python/async-jobs) for details.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options or a missing job id in the acknowledgement. `wait()` raises `JobFailedError` for an errored job and `JobTimeoutError` when its overall deadline expires. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    job = client.fetch.company_live(url="https://social.com/company/acme")
    print("Save this job id:", job.id)
    done = job.wait()
    print(done.data.result if done.data else None)
```
## check_company

Supply a company `url` or `id`. The call is free but requires at least 2 credits in the workspace.

**Python SDK**

```python [Python SDK]
def check_company(
    *,
    url: str | NotGiven | None = NOT_GIVEN,
    id: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.CheckCompanyData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `url` | `str \| NotGiven \| None` | **Required for the selected strategy.** Public Social company URL (e.g. `https://social.com/company/acme-corp`). Required unless `id` is given. |
| `id` | `str \| NotGiven \| None` | **Required for the selected strategy.** Reverse Contact company id from a previous response (e.g. `com_01jbd5vewyenebxgaz869ffe5t`). Required unless `url` is given. |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.CheckCompanyData]`. `data` contains `exists`, `last_update` and `speciality_count`.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.fetch.check_company(url="https://social.com/company/acme")
    print(result.data if result is not None else None)
```
## Related guides

See the [Python SDK overview](https://docs.reversecontact.com/sdk/python), [Async jobs](https://docs.reversecontact.com/sdk/python/async-jobs) and [Jobs](https://docs.reversecontact.com/sdk/python/jobs).

## FAQ

### How do I fetch a cached person profile in Python?

Call `client.fetch.person()` with `url` or `id`. The profile is in `result.data`. A no-match response is `None` and costs no credits.

### How do I wait for a live profile in Python?

Call `wait()` on the job returned by `client.fetch.person_live()` or `client.fetch.company_live()`. Save `job.id` before waiting to resume polling later.

### Does checking profile status cost credits?

`client.fetch.check_person()` and `client.fetch.check_company()` are free, but the workspace must have at least 2 credits.