---
name: unified-sdks
description: >-
  Use the official Unified.to SDKs (TypeScript, Python, PHP, Java, Go, C#, Ruby)
  to call the Unified.to API from code instead of hand-rolling HTTP. Use when a
  coding task should install and call a typed SDK — client construction and JWT
  auth, method naming, request/response shapes, pagination and filtering, retries,
  and error handling — across any API category.
license: MIT
metadata:
  category: sdks
  api_base: https://api.unified.to
  docs: https://docs.unified.to/reference/sdks
---

# Use the Unified.to SDKs

The Unified.to SDKs wrap the same REST API behind typed, idiomatic clients. Prefer
an SDK over raw HTTP: it is generated from the OpenAPI spec, stays in sync with the
data model, handles auth and retries, and gives you typed requests and responses.
This skill teaches an agent how to install and call the SDKs.

## When to use this skill

Use this skill when the task is to:

- Install and configure a Unified.to SDK in TypeScript, Python, PHP, Java, Go, C#, or Ruby
- Authenticate an SDK client with a workspace API key
- Call list / get / create / update / delete methods for any category
- Page, filter, and select fields through the SDK
- Handle SDK errors and configure retries

For the object shapes of a specific category, also load the matching skill (e.g.
`unified-crm`), or the foundational `unified-api` skill for the REST fundamentals.

## Prerequisites

1. A Unified.to workspace **API key** (`app.unified.to` → Settings → API Keys).
   Keep it server-side only.
2. A **connection ID** identifying the customer's connected app
   (https://docs.unified.to/concepts/embedded-components).

## Available SDKs

| Language   | Package                          | Repo / registry                                                  |
| ---------- | -------------------------------- | ---------------------------------------------------------------- |
| TypeScript | `@unified-api/typescript-sdk`    | https://www.npmjs.com/package/@unified-api/typescript-sdk        |
| Python     | `Unified-python-sdk`             | https://github.com/unified-to/unified-python-sdk                 |
| PHP        | `unified-to/unified-php-sdk`     | https://github.com/unified-to/unified-php-sdk                    |
| Java       | `to.unified:unified-java-sdk`    | https://central.sonatype.com/artifact/to.unified/unified-java-sdk |
| Go         | `unified-to/unified-go-sdk`      | https://github.com/unified-to/unified-go-sdk                     |
| C#         | `UnifiedTo`                      | https://www.nuget.org/packages/UnifiedTo                         |
| Ruby       | `unified-to/unified-ruby-sdk`    | https://github.com/unified-to/unified-ruby-sdk                   |

Each SDK's README carries language-idiomatic examples for every method.

## Core pattern

1. Construct the client with your API key as the `jwt` security value.
2. Call `<client>.<category>.<operation><Category><Object>(...)` — e.g.
   `listCrmContacts`, `createCrmContact`, `listAtsCandidates`,
   `updateAccountingInvoice`.
3. Pass a request object that always includes the `connectionId`, plus body and
   query parameters.
4. Read the typed resource off the response (the response also exposes the HTTP
   `statusCode`).

## TypeScript

```bash
npm add @unified-api/typescript-sdk
```

```typescript
import { UnifiedTo } from '@unified-api/typescript-sdk';

const sdk = new UnifiedTo({
    security: { jwt: process.env.UNIFIED_API_KEY! },
});

async function run() {
    // List
    const res = await sdk.crm.listCrmContacts({
        connectionId: process.env.CONNECTION_ID!,
        limit: 20,
    });
    if (res.statusCode === 200) {
        console.log(res.crmContacts);
    }

    // Create
    await sdk.crm.createCrmContact({
        connectionId: process.env.CONNECTION_ID!,
        crmContact: { name: 'Grace Hopper', emails: [{ email: 'grace@example.com' }] },
    });
}

run();
```

## Python

```bash
pip install Unified-python-sdk
```

```python
from unified_python_sdk import UnifiedTo
from unified_python_sdk.models import shared

with UnifiedTo(security=shared.Security(jwt="<YOUR_API_KEY>")) as unified_to:
    # List
    res = unified_to.crm.list_crm_contacts(request={
        "connection_id": "<CONNECTION_ID>",
        "limit": 20,
    })
    print(res.crm_contacts)

    # Create
    unified_to.crm.create_crm_contact(request={
        "connection_id": "<CONNECTION_ID>",
        "crm_contact": {"name": "Grace Hopper"},
    })
```

Every method also has an `await`-able `_async` variant (e.g.
`create_crm_contact_async`).

## Other languages

PHP, Java, Go, C#, and Ruby follow the same shape — construct a client with the
`jwt` security value, then call `<category>.<operation><Category><Object>`. See
each SDK's README (table above) for the exact idiomatic syntax.

## Naming conventions

Each SDK uses its language's standard naming convention for field names — e.g.
TypeScript uses camelCase (`connectionId`, `updatedGte`) while Python uses
snake_case (`connection_id`, `updated_gte`). All of the written docs use
snake_case; translate to the SDK's convention.

## Pagination, filtering & field selection

Pass the same parameters the REST API accepts as fields on the request object,
in the SDK's naming convention:

- `limit` (max 100) and `offset` (zero-based) to page. A returned count `< limit`
  means the last page.
- `updatedGte` / `updated_gte` for incremental sync.
- `query` for free-text search; per-resource filters such as `companyId`.
- `sort` and `order` to order results.
- `fields` to return only the fields you need (smaller, cheaper responses).

## Retries

The SDKs have built-in retry support with exponential backoff — configure it
per-call or globally. In TypeScript:

```typescript
const sdk = new UnifiedTo({
    security: { jwt: process.env.UNIFIED_API_KEY! },
    retryConfig: {
        strategy: 'backoff',
        backoff: { initialInterval: 1, maxInterval: 50, exponent: 1.1 },
    },
});
```

## Error handling

Failed calls raise a typed SDK error. In TypeScript, catch `UnifiedToError`,
which exposes `message`, `statusCode`, `headers`, `body`, and `rawResponse`:

```typescript
import * as errors from '@unified-api/typescript-sdk/sdk/models/errors';

try {
    await sdk.crm.listCrmContacts({ connectionId });
} catch (error) {
    if (error instanceof errors.UnifiedToError) {
        console.log(error.statusCode, error.message, error.body);
    } else {
        throw error;
    }
}
```

Common statuses: `401` (re-authorize the connection), `403` (scopes/IP), `429`
(rate limit — back off), `501` (operation unsupported by that provider).

## Generating an SDK for another language

For any language not listed, generate a client from the OpenAPI spec at
https://api.unified.to/openapi.json with a tool such as
[OpenAPI Generator](https://openapi-generator.tech/). There is also a
[Cloudflare Worker template](https://github.com/unified-to/unified-cloudflare-worker).

## References

- SDKs overview: https://docs.unified.to/reference/sdks
- REST basics: https://docs.unified.to/reference/rest
- Pagination & filtering: https://docs.unified.to/reference/pagination
- Embedded components (connections): https://docs.unified.to/concepts/embedded-components