# Integration commands: call, connect, pause

URL: /code/cli/integration/verbs · Id: `page:code/cli/integration/verbs`

> The Integration Verbs call, connect, pause as CLI commands, with inputs, result, refusals and an example.

Reference for [Integration](/business/nouns/integration), one group of [Integration commands](/code/cli/integration).

### Integration.call
Call sends one request to an upstream through an Integration, with its token filled in server-side, for endpoints no Mapping covers. [Verb page](/business/nouns/integration/call?interface=cli).

```text
npx startup-builder do Integration.call --json '<input>' [--try | --send | --do]
```

Emits [`Integration.called`](/business/events/Integration.called).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration to call through. |
| `method` | `string` | Yes | The HTTP method; `GET` runs at once. |
| `path` | `string` | Yes | The upstream path, inside the Integration’s grants. |
| `body` | `json` | No | The request body. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `integer` | Yes | The upstream’s status code. |
| `body` | `json` | No | The upstream’s response body. |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration the request went through. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
| A path outside the Integration’s grants before it leaves the platform | [`refused`](/code/api/errors/refused) | Clear what the check names, then call it again. | None. |

**Example**

```bash
npx startup-builder do Integration.call --json '{"integration":"integration_alVwjQcmRy","method":"GET","path":"/"}'
```

### Integration.connect
Connect asks an account holder to approve an outside account for one System and records the grants they approve. [Verb page](/business/nouns/integration/connect?interface=cli).

```text
npx startup-builder do Integration.connect --json '<input>' [--try | --send | --do]
```

Emits [`Integration.connected`](/business/events/Integration.connected).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `system` | [System](/business/nouns/system) | Yes | The System the Integration serves. |
| `scope` | `string` | Yes | One of `studio`, `startup` or `customer`; a person’s own account is `startup`, narrowed to them. |
| `grants` | `string[]` | Yes | The access requested, shown to the account holder before they approve. |
| `venue` | `string` | No | The id of the ad, social or app-store venue the account is on. |
| `for` | [Party](/business/nouns/party) | No | The account holder, when an Agent asks on their behalf. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration, `connecting` until approved. |
| `connectUrl` | `url` | Yes | The approval page on the upstream’s own site; it expires in one hour. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
npx startup-builder do Integration.connect --json '{"system":"system_uGWze2jvrp","scope":"studio","grants":["Example grants"]}'
```

### Integration.pause
Pause stops every call through an Integration at once and keeps its token and cursor. [Verb page](/business/nouns/integration/pause?interface=cli).

```text
npx startup-builder do Integration.pause --json '<input>' [--try | --send | --do]
```

Emits [`Integration.paused`](/business/events/Integration.paused).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration to pause. |
| `reason` | `text` | No | Why, shown to every Worker whose Action waits on it. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `integration` | [Integration](/business/nouns/integration) | Yes | The Integration, `paused`. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
npx startup-builder do Integration.pause --json '{"integration":"integration_alVwjQcmRy"}'
```