> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.joincandidhealth.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.joincandidhealth.com/_mcp/server.

This page outlines how to use our SDKs to interact with our API.
Specifically, you'll learn how to make a request to create an Encounter.

## SDK Information

candid-python

<br />

[Artifact](https://pypi.org/project/candidhealth/)

candid-node

<br />

[Artifact](https://www.npmjs.com/package/candidhealth/)

candid-ruby

<br />

[Artifact](https://rubygems.org/gems/candidhealth)

candid-csharp

<br />

[Artifact](https://www.nuget.org/packages/Candid.Net)

If your language of choice is not yet supported, you can still use our API by making requests directly to our REST endpoints. For further questions or to ask for additional language support, please reach out to our [Support team](mailto:support@joincandidhealth.com).

## Prerequisites

* Python 3, Node, or Ruby 2.7+ installed on your system
* Candid Client ID
* Candid Client Secret

## Installation

First, install the SDK using your package manager:

```bash
pip install candidhealth
```

```bash
yarn add candidhealth   # or npm install, pnpm i, etc.
```

```bash
gem install candidhealth # or bundle add candidhealth
```

```bash
dotnet add package Candid.Net
# or
nuget install Candid.Net
```

## Authentication

To make requests to our API, you'll need to use your API key for authentication. Initialize the SDK as follows:

```python
from candid.client import CandidApiClient
from candid.environment import CandidApiEnvironment

client = CandidApiClient(
    environment=CandidApiEnvironment.STAGING,
    options=CandidApiClientOptions(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET"
    )
)
```

```typescript
import { CandidApi, CandidApiClient, CandidApiEnvironment } from "candidhealth";

const client = new CandidApiClient({
    environment: CandidApiEnvironment.Staging,
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
});
```

```typescript
irequire "candidhealth"

auth = CandidApiClient::CandidApiAuthOptions.new(
  client_id: "YOUR_CLIENT_ID",
  client_secret: "YOUR_CLIENT_SECRET"
)
candidhealth = CandidApiClient::Client.new(options: auth)
```

```csharp
using Candid.Net;

var candid = new CandidClient(
    "YOUR_CLIENT_ID",
    "YOUR_CLIENT_SECRET",
    new ClientOptions { Environment = CandidEnvironment.STAGING }
);
```

Candid provides two environments, staging and production. Take care to pass the correct environment when creating your API client so that
requests are routed correctly. Be sure to not send PHI to the staging environment.

## Making an Example Request

In this example, we'll create an Encounter using the V4 API.

```python
created_encounter = client.encounters.v_4.create(
    external_id=EncounterExternalId("emr-claim-id-abcd"),
    date_of_service=Date("2023-05-23"),
    billable_status=BillableStatusType.BILLABLE,  # or BillableStatusType.NOT_BILLABLE
    responsible_party=ResponsiblePartyType.INSURANCE_PAY,  # or ResponsiblePartyType.SELF_PAY
    patient=PatientCreate(
        external_id="emr-patient-id-123",
        first_name="Loki",
        last_name="Laufeyson",
        date_of_birth=Date("1983-12-17"),
        gender=Gender.MALE,
        address=StreetAddressShortZip(
            address_1="1234 Main St",
            address_2="Apt 9876",
            city="Asgard",
            state=State.CA,
            zip_code="94109",
            zip_plus_four_code="1234",
        ),
    ),
    patient_authorized_release=True,
    billing_provider=BillingProvider(
        organization_name="Acme Health PC",
        npi="1234567890",
        tax_id="123456789",
        address=StreetAddressLongZip(
            address_1="1234 Main St",
            address_2="Apt 9876",
            city="Asgard",
            state=State.CA,
            zip_code="94109",
            zip_plus_four_code="1234",
        ),
    ),
    rendering_provider=RenderingProvider(
        first_name="Doctor",
        last_name="Strange",
        npi="9876543210",
    ),
    diagnoses=[
        DiagnosisCreate(code_type=DiagnosisTypeCode.ABF, code="Z63.88"),
        DiagnosisCreate(code_type=DiagnosisTypeCode.ABF, code="E66.66"),
    ],
    place_of_service_code=FacilityTypeCode.TELEHEALTH,
    service_lines=[
        ServiceLineCreate(
            procedure_code="99212",
            modifiers=[],
            quantity=Decimal("1.0"),
            units=ServiceLineUnits.UN,
            charge_amount_cents=1500,
            diagnosis_pointers=[0, 1],
        ),
    ],
    clinical_notes=[],
    provider_accepts_assignment=True,
    benefits_assigned_to_provider=True,
)
```

```typescript
const createEncounterResponse = await client.encounters.v4.create({
    externalId: CandidApi.EncounterExternalId("emr-claim-id-abcd"),
    dateOfService: CandidApi.Date_("2023-05-23"),
    billableStatus: "BILLABLE", // or "NOT_BILLABLE
    responsibleParty: "INSURANCE_PAY", // or "SELF_PAY"
    patient: {
        externalId: "emr-patient-id-123",
        firstName: "Loki",
        lastName: "Laufeyson",
        dateOfBirth: CandidApi.Date_("1983-12-17"),
        gender: "male",
        address: {
            address1: "1234 Main St",
            address2: "Apt 9876",
            city: "Asgard",
            state: "CA",
            zipCode: "94109",
            zipPlusFourCode: "1234",
        },
    },
    patientAuthorizedRelease: true,
    billingProvider: {
        organizationName: "Acme Health PC",
        npi: "1234567890",
        taxId: "123456789",
        address: {
            address1: "1234 Main St",
            address2: "Apt 9876",
            city: "Asgard",
            state: "CA",
            zipCode: "94109",
            zipPlusFourCode: "1234",
        },
    },
    renderingProvider: {
        firstName: "Doctor",
        lastName: "Strange",
        npi: "9876543210",
    },
    diagnoses: [
        { codeType: "ABF", code: "Z63.88" },
        { codeType: "ABF", code: "E66.66" },
    ],
    placeOfServiceCode: "02", // telemedicine
    serviceLines: [
        {
            procedureCode: "99212",
            modifiers: [],
            quantity: CandidApi.Decimal("1.0"),
            units: "UN",
            chargeAmountCents: 1500,
            diagnosisPointers: [0, 1],
        }
    ],
    clinicalNotes: [],
    providerAcceptsAssignment: true,
    benefitsAssignedToProvider: true,
});
```

## Error Handling

Each endpoint in our SDK documents which errors and exceptions can be raised
if the request fails. These can be caught and handled via native exception-handling:

```python
from candid.resources.encounters.resources.v_4.errors import EncounterExternalIdUniquenessError

try:
    created_encounter = client.encounters.v_4.create(...)
except EncounterExternalIdUniquenessError as e:
    print(f"An error occurred: {e}")
```

```typescript
if (createEncounterResponse.ok) {
    const { body: newEncounter } = createEncounterResponse;
    console.log(newEncounter.encounterId);
} else {
    console.error(createEncounterResponse.error);
}
```

## Rate Limiting

Requests to the Candid API are rate-limited by IP. Each IP is allowed 1000 requests within a 10-second rolling window.

If an IP exceeds its limit, the API will respond with `HTTP 429 - Too Many Requests`. If this occurs, it is recommended
that the client retry the request with exponential backoff logic to reduce request volume density. Exponential backoff logic is already implemented inside the Candid Health SDKs.

## Full Source Code

```python
from candid.candid_api_client import CandidApiClient, CandidApiClientOptions
from candid import (
    CandidApiEnvironment,
    EncounterExternalId,
    Date,
    PatientCreate,
    Gender,
    StreetAddressShortZip,
    State,
    StreetAddressLongZip,
    DiagnosisCreate,
    DiagnosisTypeCode,
    FacilityTypeCode,
    ServiceLineCreate,
    ServiceLineUnits,
    Decimal,
)
from candid.resources.encounter_providers.resources.v_2 import BillingProvider, RenderingProvider
from candid.resources.encounters.resources.v_4 import BillableStatusType, ResponsiblePartyType

client = CandidApiClient(
    environment=CandidApiEnvironment.STAGING,
    options=CandidApiClientOptions(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET"
    )
)

created_encounter = client.encounters.v_4.create(
    external_id=EncounterExternalId("emr-claim-id-abcd"),
    date_of_service=Date("2023-05-23"),
    billable_status=BillableStatusType.BILLABLE,  # or BillableStatusType.NOT_BILLABLE
    responsible_party=ResponsiblePartyType.INSURANCE_PAY,  # or ResponsiblePartyType.SELF_PAY
    patient=PatientCreate(
        external_id="emr-patient-id-123",
        first_name="Loki",
        last_name="Laufeyson",
        date_of_birth=Date("1983-12-17"),
        gender=Gender.MALE,
        address=StreetAddressShortZip(
            address_1="1234 Main St",
            address_2="Apt 9876",
            city="Asgard",
            state=State.CA,
            zip_code="94109",
            zip_plus_four_code="1234",
        ),
    ),
    patient_authorized_release=True,
    billing_provider=BillingProvider(
        organization_name="Acme Health PC",
        npi="1234567890",
        tax_id="123456789",
        address=StreetAddressLongZip(
            address_1="1234 Main St",
            address_2="Apt 9876",
            city="Asgard",
            state=State.CA,
            zip_code="94109",
            zip_plus_four_code="1234",
        ),
    ),
    rendering_provider=RenderingProvider(
        first_name="Doctor",
        last_name="Strange",
        npi="9876543210",
    ),
    diagnoses=[
        DiagnosisCreate(code_type=DiagnosisTypeCode.ABF, code="Z63.88"),
        DiagnosisCreate(code_type=DiagnosisTypeCode.ABF, code="E66.66"),
    ],
    place_of_service_code=FacilityTypeCode.TELEHEALTH,
    service_lines=[
        ServiceLineCreate(
            procedure_code="99212",
            modifiers=[],
            quantity=Decimal("1.0"),
            units=ServiceLineUnits.UN,
            charge_amount_cents=1500,
            diagnosis_pointers=[0, 1],
        ),
    ],
    clinical_notes=[],
    provider_accepts_assignment=True,
    benefits_assigned_to_provider=True,
)
```

```typescript
import { CandidApi, CandidApiClient, CandidApiEnvironment } from "candidhealth";

const client = new CandidApiClient({
    environment: CandidApiEnvironment.Staging,
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
});

const createEncounterResponse = await client.encounters.v4.create({
    externalId: CandidApi.EncounterExternalId("emr-claim-id-abcd"),
    dateOfService: CandidApi.Date_("2023-05-23"),
    billableStatus: "BILLABLE", // or "NOT_BILLABLE
    responsibleParty: "INSURANCE_PAY", // or "SELF_PAY"
    patient: {
        externalId: "emr-patient-id-123",
        firstName: "Loki",
        lastName: "Laufeyson",
        dateOfBirth: CandidApi.Date_("1983-12-17"),
        gender: "male",
        address: {
            address1: "1234 Main St",
            address2: "Apt 9876",
            city: "Asgard",
            state: "CA",
            zipCode: "94109",
            zipPlusFourCode: "1234",
        },
    },
    patientAuthorizedRelease: true,
    billingProvider: {
        organizationName: "Acme Health PC",
        npi: "1234567890",
        taxId: "123456789",
        address: {
            address1: "1234 Main St",
            address2: "Apt 9876",
            city: "Asgard",
            state: "CA",
            zipCode: "94109",
            zipPlusFourCode: "1234",
        },
    },
    renderingProvider: {
        firstName: "Doctor",
        lastName: "Strange",
        npi: "9876543210",
    },
    diagnoses: [
        { codeType: "ABF", code: "Z63.88" },
        { codeType: "ABF", code: "E66.66" },
    ],
    placeOfServiceCode: "02", // telemedicine
    serviceLines: [
        {
            procedureCode: "99212",
            modifiers: [],
            quantity: CandidApi.Decimal("1.0"),
            units: "UN",
            chargeAmountCents: 1500,
            diagnosisPointers: [0, 1],
        }
    ],
    clinicalNotes: [],
    providerAcceptsAssignment: true,
    benefitsAssignedToProvider: true,
});
```