# Integration routes: call, connect, pause

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

> The Integration Verbs call, connect, pause as api.sb routes, with inputs, result, refusals and an example.

Reference for [Integration](/business/nouns/integration), one group of [Integration routes](/code/api/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=api).

```text
POST /{namespace}/integrations/{integration}/call
```

Path: `integration`. Body, as JSON: the other inputs. 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
curl -X POST https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy/call \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"GET","path":"/"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "status": 1,
  "body": {},
  "integration": {
    "$id": "https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy",
    "$type": "Integration",
    "acquired": "owned",
    "scope": "studio",
    "mode": "mirror",
    "state": "connecting"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Integration.call",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### 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=api).

```text
POST /{namespace}/integrations/connect
```

Body, as JSON: the inputs. 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
curl -X POST https://api.sb/leaseline.app/integrations/connect \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"system":"system_uGWze2jvrp","scope":"studio","grants":["Example grants"]}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "integration": {
    "$id": "https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy",
    "$type": "Integration",
    "acquired": "owned",
    "scope": "studio",
    "mode": "mirror",
    "state": "connecting"
  },
  "connectUrl": "https://leaseline.app",
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Integration.connect",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

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

```text
POST /{namespace}/integrations/{integration}/pause
```

Path: `integration`. Body, as JSON: the other inputs. 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
curl -X POST https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy/pause \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "integration": {
    "$id": "https://api.sb/leaseline.app/integrations/integration_alVwjQcmRy",
    "$type": "Integration",
    "acquired": "owned",
    "scope": "studio",
    "mode": "mirror",
    "state": "connecting"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Integration.pause",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```