> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to AddressZen

The AddressZen connector lets your AI agent act in each user's AddressZen account. Each user connects their own AddressZen access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 7 tools.

**Authentication:** Bearer Token
**Categories:** Developer Tools, CRM & Sales
**Tools:** 7: 6 read, 1 write, 0 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=ADDRESSZEN)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the AddressZen connection

   In **AgentKit > Connections**, create an AddressZen connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'addresszen'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize AddressZen:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'addresszen_address_retrieve',
     toolInput: { address: 'usa_1234567' },
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "addresszen"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize AddressZen:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={"address":"usa_1234567"},
       tool_name="addresszen_address_retrieve",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their AddressZen credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'addresszen_address_retrieve',
  toolInput: {
    address: '<address>',
  },
  connector: 'addresszen',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="addresszen_address_retrieve",
    tool_input={
        "address": "<address>",
    },
    connection_name="addresszen",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `addresszen_address_retrieve`

Retrieve Address · Read-only

Get the full US-formatted address for an address suggestion ID.
Returns the address record with lines, city, state, ZIP code, ZIP+4 and other USPS address elements.
Use this after addresszen_addresses_autocomplete. Each call is a paid lookup.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `address` (`string`, required): ID of address suggestion provided by the API to fully retrieve. Example: usa_1234567.
- `filter` (`string`, optional): Comma separated whitelist of address elements to return. E.g. filter=line_1,line_2,line_3 returns only the line_1, line_2 and line_3 address elements in your response. Example: line_1,line_2,city,state,zip_code.
- `tags` (`string`, optional): A comma separated list of tags to query over. Useful if you want to specify the circumstances in which the request was made. If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar". Example: checkout,web.

Example input: `{"address":"<address>"}`

### `addresszen_addresses_autocomplete`

Autocomplete Addresses · Read-only

Get address suggestions for a partial address, in order of relevance, for search-as-you-type address entry.
Returns result.hits, each with an id, a one-line suggestion and the dataset and country.
Use this while someone types an address. Use addresszen_address_retrieve with a hit id to get the full address.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): The partial address string entered by the user to autocomplete. Example: 123 Main St Spring.
- `bias_city` (`string`, optional): Boost addresses in the named city, town or locality. Case, spaces and accents are ignored. For UK addresses use bias_posttown. Example: Springfield.
- `bias_ip` (`boolean`, optional): Biases search based on approximate geolocation of IP address. Set bias_ip=true to enable. Example: true.
- `bias_lonlat` (`string`, optional): Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is 50000. Uses the format bias_lonlat=[longitude],[latitude],[radius in meters]. Only one geospatial bias may be provided. Example: -104.99,39.74,10000.
- `bias_postal_code` (`string`, optional): Boost addresses with a matching full postal code (nine digit ZIP+4 for US addresses). Unmatched addresses still appear, ranked lower. Example: 941021234.
- `bias_postal_code_2` (`string`, optional): Boost addresses whose postal code starts with the given segment (three digit ZIP prefix for US addresses). Example: 941.
- `bias_postal_code_3` (`string`, optional): Boost addresses with a matching short postal code (five digit ZIP for US addresses). Example: 94102.
- `bias_state` (`string`, optional): Boost addresses in the named state, province or region. Example: Colorado.
- `bias_state_code` (`string`, optional): Boost addresses with a matching state or region code, e.g. CA. Example: CO.
- `box` (`string`, optional): Restrict search to a geospatial box determined by the "top-left" and "bottom-right" geolocations. Supply 4 comma separated values ordered top_left_lon,top_left_lat,bottom_right_lon,bottom_right_lat. The top-left longitude must be less than the bottom-right longitude, and the top-left latitude greater than the bottom-right latitude. A box which fails either check is ignored. Only one geospatial box can be provided. Example: -105.1,39.9,-104.8,39.6.
- `city` (`string`, optional): Restrict results to addresses in the named city, town or locality. Case, spaces and accents are ignored, so San Francisco and sanfrancisco match the same addresses. For UK addresses use post_town. Example: Springfield.
- `context` (`string`, optional): Limits search results, typically within a country. Example: usa.
- `dataset` (`string`, optional): Comma-separated list of datasets to search within. Filters results to only include addresses from the specified datasets. Useful for keys with multiple overlapping datasets enabled (e.g. paf and abp). Example: usa.
- `is_business` (`string`, optional): true restricts results to business addresses; false excludes them. For US addresses this is derived from the USPS record type (F, a firm record). Example: false. One of: `true`, `false`.
- `is_pobox` (`string`, optional): true restricts results to PO Box addresses; false excludes them. For US addresses this is derived from the USPS record type (P). Example: false. One of: `true`, `false`.
- `limit` (`integer`, optional): Specifies the maximum number of records to retrieve. By default the limit is 10. Requesting a larger result set adds latency. Example: 10.
- `postal_code` (`string`, optional): Restrict results to addresses with a matching full postal code. Case, spaces and hyphens are ignored. For US addresses the full postal code is the nine digit ZIP+4 (941021234); filter on postal_code_3 for a five digit ZIP. For UK addresses use postcode. Example: 941021234.
- `postal_code_2` (`string`, optional): Restrict results to addresses whose postal code starts with the given segment. For US addresses this is the three digit ZIP prefix (sectional center), e.g. 941 for San Francisco. Example: 941.
- `postal_code_3` (`string`, optional): Restrict results to addresses with a matching short postal code. For US addresses this is the five digit ZIP code. Example: 94102.
- `state` (`string`, optional): Restrict results to addresses in the named state, province or region, e.g. California. Case and spaces are ignored. Example: Colorado.
- `state_code` (`string`, optional): Restrict results to addresses with a matching state or region code, e.g. the two letter USPS state abbreviation CA. Case is ignored. Example: CO.

Example input: `{"query":"<query>"}`

### `addresszen_email_validate`

Validate Email Address · Read-only

Check whether an email address is valid and deliverable.
Returns result with the email, whether it is valid and deliverable, and flags such as disposable or role addresses.
Use this to check one email address. Each call is a paid lookup.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): Specifies the email address to validate. Example: jane@example.com.
- `tags` (`string`, optional): A comma separated list of tags to query over. Useful if you want to specify the circumstances in which the request was made. If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar". Example: checkout,web.

Example input: `{"query":"<query>"}`

### `addresszen_phone_number_validate`

Validate Phone Number · Read-only

Check whether a phone number is valid and get its formats and network details.
Returns result with validity, national and international formats, country and number type, and the current carrier when asked.
Use this to check one phone number. Each call is a paid lookup.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): Specifies the phone number to validate. Phone number must include a country code in an acceptable format. For instance, UK phone numbers should be prefixed with +44, 44 or 0044. Example: +442071838750.
- `current_carrier` (`boolean`, optional): When set to true, the API retrieves and populates the current network of the phone number. This operation can be slow, depending on the network and local conditions. Example: true.
- `tags` (`string`, optional): A comma separated list of tags to query over. Useful if you want to specify the circumstances in which the request was made. If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar". Example: checkout,web.

Example input: `{"query":"<query>"}`

### `addresszen_place_resolve`

Resolve Place · Read-only

Get full details for a place suggestion ID.
Returns the place with name, country, coordinates, timezone and GeoNames metadata.
Use this after addresszen_places_search. Each call is a paid lookup.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `place` (`string`, required): ID of place suggestion. Example: geonames_5398563.
- `tags` (`string`, optional): A comma separated list of tags to query over. Useful if you want to specify the circumstances in which the request was made. If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar". Example: checkout,web.

Example input: `{"place":"<place>"}`

### `addresszen_places_search`

Search Places · Read-only

Search geographical places (cities, towns, regions) across countries by name.
Returns result.hits, each with a place id and a descriptive suggestion.
Use this to find a place ID. Use addresszen_place_resolve with the id for coordinates and details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `query` (`string`, required): Specifies the place to query. Can be shortened to q=. Example: Springfield.
- `bias_country_iso` (`string`, optional): Bias by country ISO code. Uses 3 letter country code (ISO 3166-1) standard. Bias by multiple countries with a comma separated list. E.g. GBR,IRL. Example: USA.
- `bias_ip` (`boolean`, optional): Biases search based on approximate geolocation of IP address. Set bias_ip=true to enable. Example: true.
- `bias_lonlat` (`string`, optional): Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is 50000. Uses the format bias_lonlat=[longitude],[latitude],[radius in meters]. Only one geospatial bias may be provided. Example: -104.99,39.74,10000.
- `country_iso` (`string`, optional): Filter by country ISO code. Uses 3 letter country code (ISO 3166-1) standard. Filter by multiple countries with a comma separated list. E.g. GBR,IRL. Example: USA,CAN.

Example input: `{"query":"<query>"}`

### `addresszen_address_verify`

Verify US Address · Write

Verify, correct and standardize a US address against USPS CASS-certified data.
Returns the matched address with standardized lines, city, state, ZIP+4, delivery point details and match information, or no match.
Use this to check a full address someone typed. Use addresszen_addresses_autocomplete for search-as-you-type suggestions. Each call is a paid lookup.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `query` (`string`, required): The address to verify. Put the full address here, or only the street line when you also send zip_code, city and state. Example: 123 Main St, Springfield, CO, 81073.
- `city` (`string`, optional): City of the address. Example: Springfield.
- `context` (`string`, optional): Identify the country of the address to verify. Defaults to United States (USA). Example: usa.
- `state` (`string`, optional): Two-letter state abbreviation. Example: CO.
- `tags` (`string`, optional): A comma separated list of tags to query over. Useful if you want to specify the circumstances in which the request was made. If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar". Example: checkout,web.
- `zip_code` (`string`, optional): ZIP code of the address, as 81073, 810731119 or 81073-1119. Example: 81073.

Example input: `{"query":"<query>"}`

## Related

Other Developer Tools connectors ([all 200](/agentkit/connectors/?category=developer-tools)):

- [GitHub](/agentkit/connectors/github/): Scalekit connector, OAuth, 217 tools
- [Datadog](/agentkit/connectors/datadog/): Scalekit connector, API key, 105 tools
- [Linear](/agentkit/connectors/linear/): Scalekit connector, OAuth, 64 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
