Metadata-Version: 2.5
Name: meltanolabs-tap-apollo
Version: 0.1.4
Summary: Singer tap for Apollo, built with the Meltano Singer SDK.
Author-email: Max <max@meltano.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: Apollo,ELT
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.10
Requires-Dist: requests~=2.34.0
Requires-Dist: singer-sdk~=0.54.9
Requires-Dist: typing-extensions>=4.5.0; python_version < '3.13'
Provides-Extra: s3
Requires-Dist: s3fs>=2026.1.0; extra == 's3'
Description-Content-Type: text/markdown

# tap-apollo

`tap-apollo` is a Singer tap for [Apollo.io](https://www.apollo.io/), built with the
[Meltano Singer SDK](https://sdk.meltano.com). It extracts the records your team
manages in Apollo (contacts, accounts, deals, tasks, calls, sequences and
outreach emails) plus workspace reference data, through the
[Apollo REST API](https://docs.apollo.io/reference/apollo-api).

## Streams

| Stream | Endpoint | Replication |
|:--|:--|:--|
| `contacts` | `POST /contacts/search` | Incremental on `updated_at` |
| `accounts` | `POST /accounts/search` | Full table |
| `opportunities` | `GET /opportunities/search` | Full table |
| `tasks` | `POST /tasks/search` | Full table |
| `phone_calls` | `GET /phone_calls/search` | Full table |
| `sequences` | `POST /emailer_campaigns/search` | Full table |
| `emailer_messages` | `GET /emailer_messages/search` | Full table |
| `users` | `GET /users/search` | Full table |
| `email_accounts` | `GET /email_accounts` | Full table |
| `lists` | `GET /labels` | Full table |
| `custom_fields` | `GET /typed_custom_fields` | Full table |
| `contact_stages` | `GET /contact_stages` | Full table |
| `account_stages` | `GET /account_stages` | Full table |
| `opportunity_stages` | `GET /opportunity_stages` | Full table |

### Limitations

- **50,000 records per search.** Apollo's search endpoints return at most 500 pages
  of 100 records. When a stream hits that cap, the tap logs a warning and stops.
  Apollo has no updated-since filter, so `contacts` is requested newest first and
  pagination stops at the bookmark. After the first sync, each run only needs to
  page through contacts that changed since the last run.
- **API key access.** Apollo [API keys](https://docs.apollo.io/docs/create-api-key) are
  scoped to the endpoints chosen when they're created, and a stream fails with a 403 if
  the key can't call its endpoint. A master API key can call every endpoint;
  `phone_calls` always requires one. Otherwise, give the key access to each selected
  stream's endpoint, or deselect the stream.
- **Rate limits and timeouts.** Apollo limits calls per minute, hour and day, depending
  on your plan. The tap retries 429 responses, honoring `Retry-After` when Apollo sends
  it. It also retries requests that time out, either on Apollo's side (a 422 saying
  "request timed out") or after 60 seconds without a response.
- **Schemas.** Schemas in `tap_apollo/schemas/` are generated by `scripts/gen_schemas.py`
  from Apollo's OpenAPI spec and examples, plus real records from the API, because the
  spec leaves out many fields. Fields not in a schema are dropped, with a warning. To
  pick up new fields, save a sample of records per stream (one `<stream>.json` array
  each, kept out of git since they hold customer data) and rerun the script. Existing
  fields are only ever widened, never narrowed. Nested objects keep keys their schema
  doesn't list, such as custom field values keyed by ID:

  ```bash
  curl -sSLo spec.json https://docs.apollo.io/openapi/apollo-rest-api.json
  python scripts/gen_schemas.py spec.json tap_apollo/schemas path/to/samples
  ```
- **Fields with varying types are strings.** Where Apollo returns a field as different
  types (say, a string in one record and an object in another), or the type is unknown
  because it was null in every sample, the field is declared as a string, and values of
  other types are emitted JSON-encoded (`true`, `{"title": "CTO"}`). A column that mixes
  objects and plain values breaks some targets.

## Configuration

| Setting | Required | Description |
|:--|:--:|:--|
| `api_key` | Yes | Apollo API key (Settings → Integrations → API). |
| `start_date` | No | Earliest update time to extract for `contacts`. |

The SDK also supports `stream_maps`, `flattening_enabled` and the other standard
settings. Run `tap-apollo --about` to list them all.

Settings can also be set via environment variables, e.g. `TAP_APOLLO_API_KEY`
(see `.env.example`), when the tap runs with `--config=ENV`.

## Usage with Meltano

Add the tap to a Meltano project as a custom extractor:

```yaml
plugins:
  extractors:
  - name: tap-apollo
    namespace: tap_apollo
    pip_url: git+https://github.com/<org>/tap-apollo.git
    capabilities: [state, catalog, discover, about, stream-maps, structured-logging]
    settings:
    - name: api_key
      kind: string
      sensitive: true
    - name: start_date
      kind: date_iso8601
    settings_group_validation:
    - [api_key]
```

```bash
meltano install extractor tap-apollo
meltano config tap-apollo set api_key <key>
meltano run tap-apollo target-jsonl
```

## Development

```bash
uv sync
uv run pytest                                  # offline tests with a mocked API
TAP_APOLLO_API_KEY=<key> uv run pytest         # also runs the SDK's standard tests live
uv run tap-apollo --config .secrets/config.json --discover
```

`meltano.yml` in this repo is set up for local testing:

```bash
meltano install
meltano run tap-apollo target-jsonl
```
