# Transaction routes: attach, categorize, reconcile

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

> The Transaction Verbs attach, categorize, reconcile as api.sb routes, with inputs, result, refusals and an example.

Reference for [Transaction](/business/nouns/transaction), one group of [Transaction routes](/code/api/transaction).

### Transaction.attach
Attach matches a receipt File to a card Transaction, or flags the Transaction when no receipt arrives in time. [Verb page](/business/nouns/transaction/attach?interface=api).

```text
POST /{namespace}/transactions/{transaction}/attach
```

Path: `transaction`. Body, as JSON: the other inputs. Emits [`Transaction.attached`](/business/events/Transaction.attached).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction` | [Transaction](/business/nouns/transaction) | Yes | The card Transaction. |
| `file` | [File](/business/nouns/file) | No | The receipt; empty to match from the Startup’s Mailboxes. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction` | [Transaction](/business/nouns/transaction) | Yes | The Transaction with its receipt. |

**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/transactions/txn_XoxtZe3CQI/attach \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "transaction": {
    "$id": "https://api.sb/leaseline.app/transactions/txn_XoxtZe3CQI",
    "$type": "Transaction",
    "kind": "charge",
    "amount": {
      "amount": 29,
      "currency": "USD"
    }
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Transaction.attach",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Transaction.categorize
Categorize codes a Transaction to an account in the chart by the Startup’s Policy and flags a low-confidence code for review. [Verb page](/business/nouns/transaction/categorize?interface=api).

```text
POST /{namespace}/transactions/{transaction}/categorize
```

Path: `transaction`. Body, as JSON: the other inputs. Emits [`Transaction.categorized`](/business/events/Transaction.categorized).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction` | [Transaction](/business/nouns/transaction) | Yes | The Transaction to code. |
| `account` | `string` | No | The account code to use in place of the Policy’s choice. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction` | [Transaction](/business/nouns/transaction) | Yes | The coded Transaction. |
| `account` | `string` | Yes | The account code it was coded to. |
| `confidence` | `number` | Yes | How sure the code is, from 0 to 1. |

**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/transactions/txn_XoxtZe3CQI/categorize \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "transaction": {
    "$id": "https://api.sb/leaseline.app/transactions/txn_XoxtZe3CQI",
    "$type": "Transaction",
    "kind": "charge",
    "amount": {
      "amount": 29,
      "currency": "USD"
    }
  },
  "account": "Example account",
  "confidence": 1,
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Transaction.categorize",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Transaction.reconcile
Reconcile matches a Transaction on a payment rail to the ledger Entries it settles. [Verb page](/business/nouns/transaction/reconcile?interface=api).

```text
POST /{namespace}/transactions/{transaction}/reconcile
```

Path: `transaction`. Emits [`Transaction.reconciled`](/business/events/Transaction.reconciled).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction` | [Transaction](/business/nouns/transaction) | Yes | The Transaction to match. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction` | [Transaction](/business/nouns/transaction) | Yes | The reconciled Transaction. |

**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. |
| The record is not in a state that allows this Verb, so the call is refused. | [`refused`](/code/api/errors/refused) | Read the record, run the Verb that moves it to an allowed state, then retry. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/transactions/txn_XoxtZe3CQI/reconcile \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "transaction": {
    "$id": "https://api.sb/leaseline.app/transactions/txn_XoxtZe3CQI",
    "$type": "Transaction",
    "kind": "charge",
    "amount": {
      "amount": 29,
      "currency": "USD"
    }
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Transaction.reconcile",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```