# Create a connection

> Start connecting a service and get a hosted link for a person to finish it. Poll until the connection carries a credential id.

Source: https://docs.generalinput.com/api/vault/create-connection



<Endpoint method="POST" path="/v1/connections" />

<Access scope="vault:connect" />

For callers with no browser of their own. The connection is created for the member the key acts as; the person who completes it must sign in to the dashboard as that same member.

## Body [#body]

| Field     | Type      | Notes                                                                               |
| --------- | --------- | ----------------------------------------------------------------------------------- |
| `service` | string    | Required. The integration slug.                                                     |
| `label`   | string    | Optional, up to 255 characters. Shown on the connect page.                          |
| `scopes`  | string\[] | Optional, up to 100. OAuth scopes to request, from the integration's scope catalog. |

```json
{
  "service": "hubspot",
  "label": "Sales instance",
  "scopes": ["crm.objects.contacts.read"]
}
```

## Response [#response]

`201 Created`.

```json
{
  "id": "vconn_01HX…",
  "service": "hubspot",
  "label": "Sales instance",
  "status": "pending",
  "connectUrl": "https://web.generalinput.com/acme/connect/vconn_01HX…",
  "credentialId": null,
  "error": null,
  "expiresAt": "2026-09-03T11:00:00.000Z",
  "connectedAt": null,
  "createdAt": "2026-09-03T10:00:00.000Z"
}
```

| Field          | Type         | Notes                                                                                  |
| -------------- | ------------ | -------------------------------------------------------------------------------------- |
| `status`       | string       | `pending`, `connected`, `failed`, or `expired`.                                        |
| `connectUrl`   | string       | Hand this to the person. It opens the dashboard's connect flow for the service.        |
| `credentialId` | string, null | Set once `status` is `connected`. Use it with [issue a token](/api/vault/issue-token). |
| `expiresAt`    | string       | One hour after creation. A pending connection past this reads as `expired`.            |

## Errors [#errors]

| Status | When                                                                                                                            |
| ------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `service` missing, or the service has nothing to connect (hosted services and platform resources resolve without a credential). |
| `404`  | Unknown service.                                                                                                                |