# User API — Freemium (free+)

Available on all CTD plans. These endpoints give you access to your personal contacts, company lookups, relationship paths, job changes, and the full ghost email workflow. Full reference at [app.ctd.ai/account/api-access/documentation](https://app.ctd.ai/account/api-access/documentation).

## People & contacts

### GET `/user/contacts-api/people/details`

Returns details for a person identified by email or LinkedIn URL. Exactly one of `email` or `linkedin_url` must be provided.

```
curl "http://api.ctd.ai/user/contacts-api/people/details?email=john@example.com" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

### GET `/user/contacts-api/contacts/all`

Returns all contacts in your network.

```
curl "http://api.ctd.ai/user/contacts-api/contacts/all" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

### GET `/user/contacts-api/contacts/paths`

Returns warm introduction paths to a specific contact.

```
curl "http://api.ctd.ai/user/contacts-api/contacts/paths?email=john@example.com" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

## Companies

### GET `/user/contacts-api/companies/details`

Returns details for a company identified by domain or LinkedIn URL.

```
curl "http://api.ctd.ai/user/contacts-api/companies/details?domain=acme.com" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

### GET `/user/contacts-api/companies/contacts/current`

Returns people currently at a company who are in your contacts.

```
curl "http://api.ctd.ai/user/contacts-api/companies/contacts/current?domain=acme.com" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

### GET `/user/contacts-api/companies/contacts/former`

Returns people who previously worked at a company and are in your contacts.

```
curl "http://api.ctd.ai/user/contacts-api/companies/contacts/former?domain=acme.com" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

### GET `/user/contacts-api/companies/potential-contacts/current`

Returns current employees at a company who you don't directly know but may be reachable.

```
curl "http://api.ctd.ai/user/contacts-api/companies/potential-contacts/current?domain=acme.com" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

### GET `/user/contacts-api/companies/potential-contacts/former`

Former employees at a company who you don't directly know.

```
curl "http://api.ctd.ai/user/contacts-api/companies/potential-contacts/former?domain=acme.com" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

## Job changes

### GET `/user/notifications-api/public/job-changes/contacts`

Returns job change notifications for your direct connections.

```
curl "http://api.ctd.ai/user/notifications-api/public/job-changes/contacts" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

## LinkedIn import

### POST `/user/users-api/public/v1/linkedin-import/connections`

Import LinkedIn connections programmatically — same as uploading a LinkedIn data export, but via API.

```
curl -X POST "http://api.ctd.ai/user/users-api/public/v1/linkedin-import/connections" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com" \
  -H "Content-Type: application/json" \
  -d '{"connections": [...]}'
```

## Ghost emails

These endpoints let you create, manage, and send ghost emails (warm intro requests) entirely via API — useful for automating outreach workflows.

### GET `/user/asks-api/public/v1/ghost-emails`

List all ghost emails.

```
curl "http://api.ctd.ai/user/asks-api/public/v1/ghost-emails" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

### POST `/user/asks-api/public/v1/ghost-email`

Create a ghost email.

```
curl -X POST "http://api.ctd.ai/user/asks-api/public/v1/ghost-email" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com" \
  -H "Content-Type: application/json" \
  -d '{"connector_email": "jane@example.com", "target_email": "john@acme.com", "subject": "Quick intro?", "body": "Hi Jane..."}'
```

### POST `/user/asks-api/public/v1/draft`

Create a ghost email draft.

```
curl -X POST "http://api.ctd.ai/user/asks-api/public/v1/draft" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com" \
  -H "Content-Type: application/json" \
  -d '{"connector_email": "jane@example.com", "target_email": "john@acme.com"}'
```

### POST `/user/asks-api/public/v1/draft/{draft_id}/share`

Share a draft with the connector.

```
curl -X POST "http://api.ctd.ai/user/asks-api/public/v1/draft/DRAFT_ID/share" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

### POST `/user/asks-api/public/v1/ghost-emails/{draft_id}/send`

Send a ghost email.

```
curl -X POST "http://api.ctd.ai/user/asks-api/public/v1/ghost-emails/DRAFT_ID/send" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

### PATCH `/user/asks-api/public/v1/ghost-emails/{draft_id}`

Update a ghost email.

```
curl -X PATCH "http://api.ctd.ai/user/asks-api/public/v1/ghost-emails/DRAFT_ID" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Updated subject"}'
```

### POST `/user/asks-api/public/v1/ghost-emails/{draft_id}/participants`

Add a participant to a ghost email.

```
curl -X POST "http://api.ctd.ai/user/asks-api/public/v1/ghost-emails/DRAFT_ID/participants" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com" \
  -H "Content-Type: application/json" \
  -d '{"email": "participant@example.com"}'
```

### DELETE `/user/asks-api/public/v1/ghost-emails/{draft_id}/participants`

Remove a participant from a ghost email.

```
curl -X DELETE "http://api.ctd.ai/user/asks-api/public/v1/ghost-emails/DRAFT_ID/participants" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com" \
  -H "Content-Type: application/json" \
  -d '{"email": "participant@example.com"}'
```

### POST `/user/asks-api/public/v1/ghost-emails/{draft_id}/approver/share`

Approver shares a ghost email.

```
curl -X POST "http://api.ctd.ai/user/asks-api/public/v1/ghost-emails/DRAFT_ID/approver/share" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

### POST `/user/asks-api/public/v1/ghost-emails/{draft_id}/approver/decline`

Approver declines a ghost email.

```
curl -X POST "http://api.ctd.ai/user/asks-api/public/v1/ghost-emails/DRAFT_ID/approver/decline" \
  -H "ctd-api-key: YOUR_API_KEY" \
  -H "ctd-client-id: you@yourcompany.com"
```

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