# CRM sync via API

CTD exposes its full data set via REST API, allowing your CRM admin to push target account lists into CTD and pull relationship intelligence back into your CRM. Authentication requires `ctd-api-key` and `ctd-client-id` headers on every request.

The full interactive API reference is available at [app.ctd.ai/account/api-access/documentation](https://app.ctd.ai/account/api-access/documentation).

## Syncing target accounts from your CRM

The most common CRM integration pattern is pushing your target account list into CTD so it can surface warm paths to those specific accounts. The import flow uses three steps.

### Step 1: Create an import

```
POST https://api.ctd.ai/enterprise/atc-paths-api/public/v1/target-accounts/imports
```

Starts a new import and returns an `import_id`. The import opens in `ACCEPTING_BATCHES` state — ready to receive account rows.

```json
{
  "import_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
}
```

### Step 2: Upload batches of accounts

```
POST https://api.ctd.ai/enterprise/atc-paths-api/public/v1/target-accounts
```

Upload your accounts in batches of up to 50 rows. Each row must include at least one of `website` or `linkedin_url` — rows missing both are rejected and reported in `failed_reasons` without failing the rest of the batch.

```json
{
  "import_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "target_accounts": [
    {
      "website": "example.com",
      "linkedin_url": "https://www.linkedin.com/company/example",
      "account_id": "0015000000XyZ12AAA",
      "account_type": "Customer",
      "account_owner_email": "owner@yourcompany.com",
      "secondary_account_owner_email": "co-owner@yourcompany.com",
      "tier": "Tier 1",
      "custom1": "string",
      "custom2": "string",
      "custom3": "string",
      "custom4": "string",
      "number_of_opportunities": 5,
      "number_of_open_opportunities": 2
    }
  ],
  "last_batch": false
}
```

Set `last_batch: true` on your final batch to close the import and queue it for processing. Once closed, the import no longer accepts further batches.

```json
{
  "inserted": 48,
  "failed": 2,
  "failed_reasons": [
    {
      "website": null,
      "linkedin_url": null,
      "account_id": "0015000000XyZ12AAA",
      "reason": "Row is invalid, either website or linkedin_url must be provided"
    }
  ]
}
```

### Step 3: Poll import status (optional)

```
GET https://api.ctd.ai/enterprise/atc-paths-api/public/v1/target-accounts/imports/{import_id}
```

Use this to track when processing is complete after sending the final batch.

## Deleting target accounts

```
DELETE https://api.ctd.ai/enterprise/atc-paths-api/public/v1/target-accounts
```

Queues deletion of all target accounts for your enterprise. Deletion is asynchronous — the endpoint responds with `202 Accepted` and an `import_id` of type `DELETE_ALL` that you can poll via `GET /target-accounts/imports/{import_id}` to track completion.

## Custom columns

CTD supports up to four custom columns (`custom1`–`custom4`) that you can populate via the target accounts import and use for filtering in CTD. By default they appear as "Custom 1" through "Custom 4", but you can rename them to match your CRM's terminology — for example, "Region", "Segment", or "ICP Tier".

### Get current column names

```
GET https://api.ctd.ai/enterprise/atc-paths-api/public/v1/custom-columns-names
```

Returns the current display names configured for your enterprise's custom columns.

```json
{
  "mapping": [
    {
      "column_name": "custom_1",
      "display_name": "Region"
    }
  ]
}
```

### Rename custom columns

```
PATCH https://api.ctd.ai/enterprise/atc-paths-api/public/v1/rename-custom-columns
```

Updates the display names for one or more custom columns. Pass an array of `column_name` / `display_name` pairs — you can rename any subset in a single request. Renameable columns are `custom_1`, `custom_2`, `custom_3`, `custom_4`, and `custom_account_owner`.

```json
{
  "mapping": [
    { "column_name": "custom_1", "display_name": "Region" },
    { "column_name": "custom_2", "display_name": "Segment" }
  ]
}
```

## Other available endpoints

The full API covers everything CTD knows about your network. Key endpoints beyond target accounts:

- **Paths** — search paths to a company or person, filter by stage, get paths through a specific connector, update path stage by ID
- **Reachable people and companies** — list everyone your network can reach, globally or filtered
- **Job changes** — get recent job change signals for contacts in your network
- **Activities** — retrieve asks and ghost email activity

See the full reference at [app.ctd.ai/account/api-access/documentation](https://app.ctd.ai/account/api-access/documentation).

Have a question or running into an issue? Email us at [support@ctd.ai](mailto:support@ctd.ai) — we're happy to help.