# Human routes: hold, invite, onboard, recruit

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

> The Human Verbs hold, invite, onboard, recruit as api.sb routes, with inputs, result, refusals and an example.

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

### Human.hold
Hold sets aside part of a supplying Human’s earned balance against an open Dispute or an Order inside its clearance period. [Verb page](/business/nouns/human/hold?interface=api).

```text
POST /{namespace}/humans/{human}/hold
```

Path: `human`. Body, as JSON: the other inputs. Emits [`Human.held`](/business/events/Human.held).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `human` | [Human](/business/nouns/human) | Yes | The payee. |
| `amount` | `money` | Yes | The amount to hold. |
| `cause` | `string` | Yes | The Order or Dispute the hold cites. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `human` | [Human](/business/nouns/human) | Yes | The payee, with the held amount recorded. |

**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/humans/human_EeCsrv4AOW/hold \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":{"amount":29,"currency":"USD"},"cause":"Example cause"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "human": {
    "$id": "https://api.sb/leaseline.app/humans/human_EeCsrv4AOW",
    "$type": "Human",
    "name": "Dana Okafor",
    "email": "dana@leaseline.app"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Human.hold",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Human.invite
Invite asks a person to join a Startup in a named Role, sharing that Role’s work with its Agent. [Verb page](/business/nouns/human/invite?interface=api).

```text
POST /{namespace}/humans/invite
```

Body, as JSON: the inputs. Emits [`Human.invited`](/business/events/Human.invited).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `email` | Yes | Where the invitation goes. |
| `role` | [Role](/business/nouns/role) | Yes | The Role offered. |
| `access` | `string` | No | The Access Level the person holds in the app, apart from the Role: `admin`, `member` or `viewer`. Owner is never invited. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `human` | [Human](/business/nouns/human) | Yes | The invited Human. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The input does not match the schema of the operation. | [`invalid-input`](/code/api/errors/invalid-input) | Read the schema of the operation, then send every required field with the right type. | None. |
| 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 changed since it was read, so the write would overwrite a newer version. | [`conflict`](/code/api/errors/conflict) | Read the record again, then retry the write against its current state. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/humans/invite \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"dana@leaseline.app","role":"role_oloMFMUeCH"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "human": {
    "$id": "https://api.sb/leaseline.app/humans/human_SUMqLjx79R",
    "$type": "Human",
    "name": "Dana Okafor",
    "email": "dana@leaseline.app"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Human.invite",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Human.onboard
Onboard admits a recruited Human to supply work once their identity, Credentials and payout details verify. [Verb page](/business/nouns/human/onboard?interface=api).

```text
POST /{namespace}/humans/{human}/onboard
```

Path: `human`. Emits [`Human.onboarded`](/business/events/Human.onboarded).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `human` | [Human](/business/nouns/human) | Yes | The recruited Human. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `human` | [Human](/business/nouns/human) | Yes | The Human, able to take Tasks. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The input does not match the schema of the operation. | [`invalid-input`](/code/api/errors/invalid-input) | Read the schema of the operation, then send every required field with the right type. | None. |
| 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/humans/human_EeCsrv4AOW/onboard \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "human": {
    "$id": "https://api.sb/leaseline.app/humans/human_EeCsrv4AOW",
    "$type": "Human",
    "name": "Dana Okafor",
    "email": "dana@leaseline.app"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Human.onboard",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Human.recruit
Recruit invites a person to supply credentialed work to a Startup through its supply App. [Verb page](/business/nouns/human/recruit?interface=api).

```text
POST /{namespace}/humans/recruit
```

Body, as JSON: the inputs. Emits [`Human.recruited`](/business/events/Human.recruited).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `email` | Yes | Where the invitation goes. |
| `credential` | `string` | No | The Credential the work requires. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `human` | [Human](/business/nouns/human) | Yes | The recruited Human. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The input does not match the schema of the operation. | [`invalid-input`](/code/api/errors/invalid-input) | Read the schema of the operation, then send every required field with the right type. | None. |
| 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/humans/recruit \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"dana@leaseline.app"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "human": {
    "$id": "https://api.sb/leaseline.app/humans/human_SUMqLjx79R",
    "$type": "Human",
    "name": "Dana Okafor",
    "email": "dana@leaseline.app"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Human.recruit",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```