> For the complete documentation index, see [llms.txt](https://docs.biti.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.biti.so/api-reference/connect.md).

# connect

Link a customer to your service and read what they allowed.

| Endpoint                                                                     | Purpose                   |
| ---------------------------------------------------------------------------- | ------------------------- |
| [`POST /partner/v1/connect-request`](#post-partnerv1connect-request)         | Ask a customer to connect |
| [`POST /partner/v1/connect-status`](#post-partnerv1connect-status)           | Poll a connect request    |
| [`POST /partner/v1/exchange-login-code`](#post-partnerv1exchange-login-code) | Exchange a login code     |
| [`GET /partner/v1/profile`](#get-partnerv1profile)                           | Read the customer profile |
| [`GET /partner/v1/wallets`](#get-partnerv1wallets)                           | List the connected wallet |
| [`POST /partner/v1/notify`](#post-partnerv1notify)                           | Send a notification       |
| [`POST /partner/v1/disconnect`](#post-partnerv1disconnect)                   | Disconnect a customer     |

## POST /partner/v1/connect-request

**Ask a customer to connect**

{% hint style="info" %}
Auth: send `client_id` and `client_secret` in the request body. Call it from your server only.
{% endhint %}

Ask a customer, by phone number, to link their Biti account to your service. The call returns a `request_token` and install links. A phone number with no Biti account is not an error. The customer signs up first, then sees the request.

`expires_in` is in seconds. `install` holds a `deeplink` that opens the consent sheet in Biti. It also holds links to the Android and iOS stores for customers who do not have the app.

**Errors:**

* Invalid client credentials
* A scope that does not exist, or that your app may not ask for

### Parameters

| Name            | Type   | Required | Description                                                                     |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `client_id`     | string | yes      | Your client ID.                                                                 |
| `client_secret` | string | yes      | Your client secret. Server only.                                                |
| `phone`         | string | yes      | Customer phone number, for example `+252615123456`.                             |
| `scopes`        | string | yes      | Scopes to ask for, separated by commas, for example `wallet.read,profile.read`. |
| `device`        | string | no       | Device information.                                                             |

### Request

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST "https://api.biti.so/partner/v1/connect-request" \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "phone": "+252615123456",
  "scopes": "wallet.read,profile.read"
}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.biti.so/partner/v1/connect-request"
headers = {
    "Content-Type": "application/json",
}
payload = {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "phone": "+252615123456",
    "scopes": "wallet.read,profile.read",
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://api.biti.so/partner/v1/connect-request", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "phone": "+252615123456",
    "scopes": "wallet.read,profile.read"
  }),
});
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

### Response

```json
{
  "success": true,
  "message": "",
  "data": {
    "request_token": "crq_8H2k...",
    "expires_in": 600,
    "install": {
      "deeplink": "biti://connect/crq_8H2k..."
    }
  }
}
```

***

## POST /partner/v1/connect-status

**Poll a connect request**

{% hint style="info" %}
Auth: send `client_id` and `client_secret` in the request body. Call it from your server only.
{% endhint %}

Poll until the status is no longer `pending`. The first poll that sees `approved` returns the access token. The token is returned only once, so store it at once.

While the customer has not answered, `status` is `pending` and the answer has no token. Send the token in the `X-Biti-Token` header on customer endpoints.

**Errors:**

* Invalid client credentials
* Unknown or expired `request_token`

### Parameters

| Name            | Type   | Required | Description                                 |
| --------------- | ------ | -------- | ------------------------------------------- |
| `client_id`     | string | yes      | Your client ID.                             |
| `client_secret` | string | yes      | Your client secret. Server only.            |
| `request_token` | string | yes      | The `request_token` from `connect-request`. |

### Request

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST "https://api.biti.so/partner/v1/connect-status" \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "request_token": "crq_8H2k..."
}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.biti.so/partner/v1/connect-status"
headers = {
    "Content-Type": "application/json",
}
payload = {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "request_token": "crq_8H2k...",
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://api.biti.so/partner/v1/connect-status", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "request_token": "crq_8H2k..."
  }),
});
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

### Response

```json
{
  "success": true,
  "message": "",
  "data": {
    "status": "approved",
    "access_token": "bat_Qm9...",
    "expires_at": "2027-02-16 10:00:00",
    "scopes": [
      "wallet.read",
      "profile.read"
    ],
    "user": {
      "full_name": "Abdi Salam",
      "phone": "+25261***126"
    }
  }
}
```

***

## POST /partner/v1/exchange-login-code

**Exchange a login code**

{% hint style="info" %}
Auth: send `client_id` and `client_secret` in the request body. Call it from your server only.
{% endhint %}

Swap the one-time code from `biti.login()` in the Biti mini browser for an access token. The code lives 2 minutes. The app must have Connect enabled. Scopes are limited to the Connect scopes (not `wallet.pay`).

**Errors:**

* Invalid client credentials
* The code expired or was already used
* Connect is not enabled for the app

### Parameters

| Name            | Type   | Required | Description                            |
| --------------- | ------ | -------- | -------------------------------------- |
| `client_id`     | string | yes      | Your client ID.                        |
| `client_secret` | string | yes      | Your client secret. Server only.       |
| `code`          | string | yes      | The code that `biti.login()` returned. |

### Request

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST "https://api.biti.so/partner/v1/exchange-login-code" \
  -H "Content-Type: application/json" \
  -d '{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code": "lc_51x..."
}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.biti.so/partner/v1/exchange-login-code"
headers = {
    "Content-Type": "application/json",
}
payload = {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "lc_51x...",
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://api.biti.so/partner/v1/exchange-login-code", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "lc_51x..."
  }),
});
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

### Response

```json
{
  "success": true,
  "message": "",
  "data": {
    "access_token": "bat_Qm9...",
    "expires_at": "2027-02-16 10:00:00",
    "scopes": [
      "profile.read",
      "wallet.read"
    ],
    "user": {
      "full_name": "Abdi Salam",
      "phone": "+25261***126"
    }
  }
}
```

***

## GET /partner/v1/profile

**Read the customer profile**

{% hint style="info" %}
Auth: send the customer token in the `X-Biti-Token` header. Do not send `client_id` or `client_secret`.
{% endhint %}

Read the profile of the connected customer. The customer must have granted `profile.read`. You can call it with GET or POST.

This endpoint also answers to GET.

The answer holds the customer name, email and phone, limited to the scopes the customer granted.

**Errors:**

* Access token required
* Missing scope `profile.read`

**GET only.** Send the customer token in `X-Biti-Token`.

### Parameters

This call has no parameters.

### Request

{% tabs %}
{% tab title="curl" %}

```bash
curl -X GET "https://api.biti.so/partner/v1/profile" \
  -H "X-Biti-Token: YOUR_ACCESS_TOKEN"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.biti.so/partner/v1/profile"
headers = {
    "X-Biti-Token": "YOUR_ACCESS_TOKEN",
}

response = requests.get(url, headers=headers)
print(response.json())
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://api.biti.so/partner/v1/profile", {
  method: "GET",
  headers: {
    "X-Biti-Token": "YOUR_ACCESS_TOKEN"
  },
});
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

### Response

```json
{
  "success": true,
  "message": "",
  "data": {
    "full_name": "Abdi Salam",
    "phone": "+252615123456"
  }
}
```

***

## GET /partner/v1/wallets

**List the connected wallet**

{% hint style="info" %}
Auth: send the customer token in the `X-Biti-Token` header. Do not send `client_id` or `client_secret`.
{% endhint %}

Return the wallet that the customer connected. A connection holds one wallet only, so the list has one item. You can call it with GET or POST.

This endpoint also answers to GET.

To read balance and status of that wallet, use [`connected-wallet`](broken://pages/192832e1bbff7c756427c747a9fbbf93cac9ebd8#post-partnerv1connected-wallet).

**Errors:**

* Access token required
* Missing scope `wallet.read`
* No wallet connected

**GET only.** Send the customer token in `X-Biti-Token`.

### Parameters

This call has no parameters.

### Request

{% tabs %}
{% tab title="curl" %}

```bash
curl -X GET "https://api.biti.so/partner/v1/wallets" \
  -H "X-Biti-Token: YOUR_ACCESS_TOKEN"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.biti.so/partner/v1/wallets"
headers = {
    "X-Biti-Token": "YOUR_ACCESS_TOKEN",
}

response = requests.get(url, headers=headers)
print(response.json())
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://api.biti.so/partner/v1/wallets", {
  method: "GET",
  headers: {
    "X-Biti-Token": "YOUR_ACCESS_TOKEN"
  },
});
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

### Response

```json
{
  "success": true,
  "message": "",
  "data": {
    "wallets": [
      {
        "id": "WAL-0001",
        "account_number": "618629126",
        "name": "Main Wallet",
        "status": "Active",
        "is_default": true,
        "account": {
          "type": "Personal",
          "category": "Wallet",
          "is_joint": false
        },
        "currency": {
          "code": "USD",
          "symbol": "$",
          "fraction_units": 100,
          "precision": 2
        },
        "balance": {
          "available": 412.5,
          "on_hold": 0,
          "total": 412.5
        },
        "restrictions": {
          "frozen": false,
          "send_allowed": true,
          "receive_allowed": true
        }
      }
    ],
    "has_wallet": true,
    "create_wallet_deeplink": "biti://wallets/new"
  }
}
```

***

## POST /partner/v1/notify

**Send a notification**

{% hint style="info" %}
Auth: send the customer token in the `X-Biti-Token` header. Do not send `client_id` or `client_secret`.
{% endhint %}

Send a notification to the connected customer. The customer must have granted `notifications.send`.

**Errors:**

* Access token required
* Missing scope `notifications.send`

### Parameters

| Name         | Type   | Required | Description                                              |
| ------------ | ------ | -------- | -------------------------------------------------------- |
| `title`      | string | yes      | Notification title.                                      |
| `message`    | string | yes      | Notification text.                                       |
| `action_url` | string | no       | Link that opens when the customer taps the notification. |

### Request

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST "https://api.biti.so/partner/v1/notify" \
  -H "Content-Type: application/json" \
  -H "X-Biti-Token: YOUR_ACCESS_TOKEN" \
  -d '{
  "title": "Order ORD-1042",
  "message": "Your order is on the way."
}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.biti.so/partner/v1/notify"
headers = {
    "Content-Type": "application/json",
    "X-Biti-Token": "YOUR_ACCESS_TOKEN",
}
payload = {
    "title": "Order ORD-1042",
    "message": "Your order is on the way.",
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://api.biti.so/partner/v1/notify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Biti-Token": "YOUR_ACCESS_TOKEN"
  },
  body: JSON.stringify({
    "title": "Order ORD-1042",
    "message": "Your order is on the way."
  }),
});
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

### Response

```json
{
  "success": true,
  "message": "",
  "data": {}
}
```

***

## POST /partner/v1/disconnect

**Disconnect a customer**

{% hint style="info" %}
Auth: send the customer token in the `X-Biti-Token` header. Do not send `client_id` or `client_secret`.
{% endhint %}

End the connection. The access token stops working. The customer can also disconnect at any time in Settings, Connected apps.

**Errors:**

* Access token required

### Parameters

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |

### Request

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST "https://api.biti.so/partner/v1/disconnect" \
  -H "Content-Type: application/json" \
  -H "X-Biti-Token: YOUR_ACCESS_TOKEN" \
  -d '{}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.biti.so/partner/v1/disconnect"
headers = {
    "Content-Type": "application/json",
    "X-Biti-Token": "YOUR_ACCESS_TOKEN",
}
payload = {}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const response = await fetch("https://api.biti.so/partner/v1/disconnect", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Biti-Token": "YOUR_ACCESS_TOKEN"
  },
  body: JSON.stringify({}),
});
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

### Response

```json
{
  "success": true,
  "message": "",
  "data": {}
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.biti.so/api-reference/connect.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
