# Life of a call

URL: /products/api/life-of-a-call · Id: `page:products/api/life-of-a-call`

> One call to a Startup's API, from the key it carries to the Invoice it lands on, with every check and record along the way.

Harbor Residential's property software renews a lease through Leaseline's API. One call passes six checks in a fixed order, records one [Action](/business/nouns/action), and sends one [Event](/business/nouns/event) to every receiver that asked for it.

## The call
Leaseline declares a `Lease` [Noun](/business/nouns/noun) with a `Lease.renew` [Verb](/business/nouns/verb). Harbor Residential's sync calls it with its own key:

```bash
curl -X POST https://api.leaseline.app/leases/lease_4loEed1JG4/renew \
  -H "Authorization: Bearer $LEASELINE_API_KEY" \
  -H "Idempotency-Key: harbor-renewal-5c" \
  -H "Content-Type: application/json" \
  -d '{"months":12}'
```

```json
{
  "api": "https://api.leaseline.app",
  "action": {
    "$id": "https://api.leaseline.app/actions/act_br07HsG8MG",
    "operation": "Lease.renew",
    "status": "done",
    "mode": "do"
  },
  "lease": {
    "$id": "https://api.leaseline.app/leases/lease_4loEed1JG4",
    "$type": "Lease",
    "status": "renewed"
  },
  "links": { "self": "https://api.leaseline.app/actions/act_br07HsG8MG" }
}
```

## Six checks, in order
| Step | What is checked | On failure |
| --- | --- | --- |
| Address | `api.leaseline.app` resolves to Leaseline's [Publication](/business/nouns/publication) | `404` [`not-found`](/code/api/errors/not-found) |
| Key | The key is valid, names one [Tenant](/business/nouns/tenant), and picks `test` or `live` | `401` [`unauthorized`](/code/api/errors/unauthorized); no Action |
| [Version](/business/nouns/version) | A version in the path, else the Tenant's `apiVersion` | Answered in that version's shape |
| Scope and [Permissions](/business/nouns/permission) | The key and the caller's [Role](/business/nouns/role) allow `Lease.renew` | `403` [`forbidden`](/code/api/errors/forbidden); no Action |
| [Entitlement](/business/nouns/entitlement) | Harbor Residential's [Offer](/business/nouns/offer) grants the Verb | `402` [`payment-required`](/code/api/errors/payment-required), naming the Offer that covers it |
| [Limit](/business/nouns/limit) | The call fits the plan's count and rate | The Offer's `atBound`, or `429` [`rate-limited`](/code/api/errors/rate-limited) with `Retry-After` |

The first four fail at the door, so nothing is recorded. The last two are decisions about the business, so they land on the record.

## What the call leaves behind
| Record | What it holds |
| --- | --- |
| The Action | The Verb, its input, its result, `by` the caller and `for` Harbor Residential |
| The Event | `Lease.renewed`, numbered by `seq`, kept forever |
| Deliveries | One per [Watch](/business/nouns/watch) that selects `Lease.renewed` and may read this lease |
| A [Meter](/business/nouns/meter) [Entry](/business/nouns/entry) | One unit, when the Offer meters the Verb, counted exactly once |
| The [Invoice](/business/nouns/invoice) | The period's metered lines, at the end of the period |

The `Idempotency-Key` makes a retry safe: the same key returns the first Action and runs nothing twice. [Idempotency](/code/api/guides/idempotency) covers the rules.

## The same Verb, from the builder plane
Leaseline's [Success Manager](/agents/customer/success-manager) agent renews leases through [api.sb](/code/platform/api-sb) at `api.sb/leaseline.app`, with its Role's key. The Action, the Event and the Watches are the same.

The address, the key and the scope differ: the agent reaches every Tenant its Role grants, and Harbor Residential's key reaches one. [Anatomy of an API](/products/api/anatomy) compares the two planes.